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NAME 

intro - description of routines in the Graphics Library and Distributed 
Graphics Library 

OVERVIEW 

This manual is the reference manual for the routines of the Graphics 
Library (GL) and the Distributed Graphics Library (DGL). For a more 
tutorial introduction to the GL and DGL, see the Graphics Library 
Programmer' s Guide and the ' 'Using the GL/DGL Interfaces" section 
of the 4Sight Programmer' s Guide. 

In general, all routines in the GL are supported in the DGL. However, in 
some routines there are minor differences. In addition, some routines 
(dglopen and dglclose) are supported in the DGL but not the GL. Where 
there is a difference for a routine, it is noted on its manual page. 

The manual pages are available on-line. To view them, use the IRIX 
command: 

man routine-name <Enter> 

HOW A MANUAL PAGE IS ORGANIZED 

A manual page provides the specification of a GL or DGL routine. 
Because these pages are intended as on-line reference material, they 
tend to be terse. A page is divided into a number of sections: 

NAME 

lists the name of the routine or routines described by the manual 
page. 

FORTRAN SPECIFICATION 

lists the type declarations for the routine and its parameters. 

PARAMETERS 

describes the parameters of the routine. 

FUNCTION RETURN VALUE 

describes what the routine returns if it is a function. 
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DESCRIPTION 

describes how to use the routine. 

SEE ALSO 

lists related routines or other sources of information. 

EXAMPLE 

gives an example of how the routine is used. 

NOTES 

highlights information concerning the limitations of the routine and 
differences in its behavior on the various IRIS-4D models. 

BUGS 

describes deviations from the specified behavior that may be fixed in 
a future release. 

HEADER FILES 

There are three header files in lusrl 'include/ gl that you should probably 
include in code that calls routines from the Graphics Library. The files 
%xzfglh,fget.h, and /device. h. 
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acbuf - operate on the accumulation buffer 

acsize - specify the number of bitplanes per color component in the 
accumulation buffer 

addtop - adds items to an existing pop-up menu 

afunct - specify alpha test function 

arc, arci, arcs - draw a circular arc 

arcf, arcfi, arcfs - draw a filled circular arc 

attach - attaches the cursor to two valuators 

backbu - enable and disable drawing to the back buffer 

backfa - turns backfacing polygon removal on and off 

bbox2, bbox2i, bbox2s - culls and prunes to bounding box and 
minimum pixel radius 

bgnclo - delimit the vertices of a closed line 

bgnlin - delimit the vertices of a line 

bgnpoi - delimit the interpretation of vertex routines as points 

bgnpol - delimit the vertices of a polygon 

bgnqst - delimit the vertices of a quadrilateral strip 

bgnsur - delimit a NURBS surface definition 

bgntme - delimit the vertices of a triangle mesh 

bgntri - delimit a NURBS surface trimming loop 

blanks - controls screen blanking 

blankt - sets the screen blanking timeout 

blendf - computes a blended color value for a pixel 

blink - changes a color map entry at a selectable rate 

blkqre - reads multiple entries from the queue 

c3f, c3i, c3s, c4f, c4i, c4s - sets the RGB (or RGBA) values for the 
current color vector 
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callob - draws an instance of an object 

charst - draws a string of raster characters on the screen 

chunks - specifies minimum object size in memory 

circ, circi, circs - outlines a circle 

circf, circfi, circf s - draws a filled circle 

clear - clears the viewport 

clearh - sets the hitcode to zero 

clippl - specify a plane against which all geometry is clipped 

clkon, clkoff- control keyboard click 

closeo - closes an object definition 

cmode - sets color map mode as the current mode. 

cmov, cmovi, cmovs, cmov2, cmov2i, cmov2s - updates the current 
character position 

color, colorf - sets the color index in the current draw mode 

compac - compacts the memory storage of an object 

concav - allows the system to draw concave polygons ^ 

cpack - specifies RGBA color with a single packed 32-bit integer 

crv - draws a curve 

crvn - draws a series of curve segments 

curori - sets the origin of a cursor 

curson, cursof - control cursor visibility by window 

cursty - defines the type and/or size of cursor 

curveb - selects a basis matrix used to draw curves 

curvei - draws a curve segment 

curvep - sets number of line segments used to draw a curve segment 

cyclem - cycles between color maps at a specified rate 
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czclea - clears the color bitplanes and the z-buffer simultaneously 

dbtext - sets the dial and button box text display 

defbas - defines a basis matrix 

defcur - defines a cursor glyph 

deflin - defines a linestyle 

defpat - defines patterns 

defras - defines a raster font 

delobj - deletes an object 

deltag - deletes a tag from the current open object 

depthc - turns depth-cue mode on and off 

dglclo - closes the DGL server connection 

dglope - opens a DGL connection to a graphics server 

dopup - displays the specified pop-up menu 

double - sets the display mode to double buffer mode 

draw, drawi, draws, draw2, draw2i, draw2s - draws aline 

drawmo - selects which GL framebuffer is drawable 

editob - opens an object definition for editing 

endclo - delimit the vertices of a closed line 

endfee - control feedback mode 

endful - ends full-screen mode 

endlin - delimit the vertices of a line 

endpic - turns off picking mode 

endpoi - delimit the interpretation of vertex routines as points 

endpol - delimit the vertices of a polygon 

endpup - obsolete routine 

endqst - delimit the vertices of a quadrilateral strip 
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endsel - turns off selecting mode 

endsur - delimit a NURBS surface definition 

endtme - delimit the vertices of a triangle mesh 

endtri - delimit a NURBS surface trimming loop 

feedba - control feedback mode 

finish - blocks until the Geometry Pipeline is empty 

fogver - specify fog density for per-vertex atmospheric effects 

font - selects a raster font for drawing text strings 

foregr - prevents a graphical process from being put into the back- 
ground 

freepu - deallocates a menu 

frontb - enable and disable drawing to the front buffer 

frontf- turns frontfacing polygon removal on and off 

fudge - specifies fudge values that are added to a graphics window 

fullsc - allows a program write to the entire screen 

gammar - defines a color map ramp for gamma correction \^ 

gbegin - create a window that occupies the entire screen 

gconfi - reconfigures the system 

genobj - returns a unique integer for use as an object identifier 

gentag - returns a unique integer for use as a tag 

getbac - returns whether backfacing polygons will appear 

getbuf - indicates which buffers are enabled for writing 

getbut - returns the state of a button 

getcmm - returns the current color map mode 

getcol - returns the current color 

getcpo - returns the current character position 
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getcur - returns the cursor characteristics 

getdcm - indicates whether depth-cue mode is on or off 

getdep - obsolete routine 

getdes - returns the character characteristics 

getdev - reads a list of valuators at one time 

getdis - returns the current display mode 

getdra - returns the current drawing mode 

getfon - returns the current raster font number 

getgde - gets graphics system description 

getgpo - gets the current graphics position 

gethei - returns the maximum character height in the current raster font 

gethit - returns the current hitcode 

getlsb - has no function in the current system 

getlsr - returns the linestyle repeat count 

getlst - returns the current linestyle 

getlwi - returns the current linewidth 

getmap - returns the number of the current color map 

getmat - returns a copy of a transformation matrix 

getmco - gets a copy of the RGB values for a color map entry 

getmmo - returns the current matrix mode 

getmon - returns the type of the current display monitor 

getnur - returns the current value of a trimmed NURBS surfaces 
display property 

getope - returns the identifier of the currently open object 

getori - returns the position of a graphics window 

getoth - obsolete routine 
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getpat - returns the index of the current pattern 

getpla - returns the number of available bitplanes 

getpor - obsolete routine 

getres - returns the state of linestyle reset mode ' g- 

getsb - read back the current computed screen bounding box V 

getscr - returns the current screen mask 

getsha - obsolete routine 

getsiz - returns the size of a graphics window 

getsm - returns the current shading model 

getval - returns the current state of a valuator 

getvid - get video hardware registers 

getvie - gets a copy of the dimensions of the current viewport 

getwri - returns the current writemask 

getwsc - returns the screen upon which the current window appears 

getzbu - returns whether z-buffering is on or off s- 

gexit - exits graphics V 

gflush - flushs the DGL client buffer 

ginit - create a window that occupies the entire screen 

glcomp - controls compatibility modes 

greset - resets graphics state 

gRGBco - gets the current RGB color values 

gRGBcu - obsolete routine 

gRGBma - returns the current RGB writemask 

gselec - puts the system in selecting mode 

gsync- waits for a vertical retrace period 

gversi - returns graphics hardware and library version information ^ 
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iconsi - specifies the icon size of a window 

iconti - assigns the icon title for the current graphics window. 

imakeb - registers the screen background process 

initna - initializes the name stack 

ismex - obsolete routine 

isobj - returns whether an object exists 

isqueu -returns whether the specified device is enabled for queuing 

istag - returns whether a tag exists in the current open object 

keepas - specifies the aspect ratio of a graphics window 

lampon, lampof - control the keyboard display lights 

linesm - specify antialiasing of lines 

linewi - specifies width of lines 

lmbind - selects a new material, light source, or lighting model 

lmcolo - change the effect of color commands while lighting is active 

lmdef - defines or modifies a material, light source, or lighting model 

loadma - loads a transformation matrix 

loadna - loads a name onto the name stack 

logico - specifies a logical operation for pixel writes 

lookat - defines a viewing transformation 

Irectr - reads a rectangular array of pixels into CPU memory 

lrectw - draws a rectangular array of pixels into the frame buffer 

IRGBra - sets the range of RGB colors used for depth-cueing 

lsback - controls whether the ends of a line segment are colored 

lsetde - sets the depth range 

Ishade - sets range of color indices used for depth-cueing 

lsrepe - sets a repeat factor for the current linestyle 
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makeob - creates an object 

maketa - numbers a routine in the display list 

mapcol - changes a color map entry 

mapw - maps a point on the screen into a line in 3-D world coordinates 

mapw2 - maps a point on the screen into 2-D world coordinates 

maxsiz - specifies the maximum size of a graphics window 

minsiz - specifies the minimum size of a graphics window 

mmode - sets the current matrix mode 

move, movei, moves, move2, move2i, move2s .- moves the current 
graphics position to a specified point 

mswapb - swap multiple framebuffers simultaneously 

multim - organizes the color map as a number of smaller maps 

multma - premultiplies the current transformation matrix 

n3f- specifies a normal 

newpup - allocates and initializes a stmcture for a new menu 

newtag - creates a new tag within an object relative to an existing tag I 

nmode - specify renormalization of normals 

nobord - specifies a window without any borders 

noise - filters valuator motion 

noport - specifies that a program does not need screen space 

normal - obsolete routine 

nurbsc - controls the shape of a NURBS trimming curve 

nurbss - controls the shape of a NURBS surface 

objdel - deletes routines from an object 

objins - inserts routines in an object at a specified location 

objrep - overwrites existing display list routines with new ones 
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onemap - organizes the color map as one large map 

ortho, ortho2 - define an orthographic projection transformation 

overla - allocates bitplanes for display of overlay colors 

pageco - sets the color of the textport background 

passth - passes a single token through the Geometry Pipeline 

patch - draws a surface patch 

patchb - sets current basis matrices 

patchc - sets the number of curves used to represent a patch 

patchp - sets the precision at which curves are drawn in a patch 

pclos - closes a filled polygon 

pdr, pdri, pdrs, pdr2, pdr2i, pdr2s - specifies the next point of a 
polygon 

perspe - defines a perspective projection transformation 

pick - puts the system in picking mode 

picksi - sets the dimensions of the picking region 

pixmod - specify pixel transfer mode parameters 

pmv, pmvi, pmvs, pmv2, pmv2i, pmv2s - specifies the first point of a 
polygon 

pnt, pnti, pnts, pnt2, pnt2i, pnt2s - draws a point 

pntsmo - specify antialiasing of points 

polarv - defines the viewer's position in polar coordinates 

polf, polfi, polfs, polf2, polf2i, polf2s - draws a filled polygon 

poly, polyi, polys, poly2, poly2i, poly2s - outlines a polygon 

polymo - control the rendering of polygons 

polysm - specify antialiasing of polygons 

popatt - pops the attribute stack 

popmat - pops the transformation matrix stack 
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popnam - pops a name off the name stack 

popvie - pops the viewport stack 

prefpo - specifies the preferred location and size of a graphics window 

prefsi - specifies the preferred size of a graphics window ^ 

pupmod - obsolete routine ^ 

push at - pushes down the attribute stack 

pushma - pushes down the transformation matrix stack 

pushna - pushes a new name on the name stack 

pushvi - pushes down the viewport stack 

pwlcur - describes a piecewise linear trimming curve for NURBS sur- 
faces 

qdevic - queues a device 

qenter - creates an event queue entry 

qgetfd - returns the file descriptor of the event queue 

qread - reads the first entry in the event queue 

qreset - empties the event queue 

qtest - checks the contents of the event queue 

rcrv - draws a rational curve 

rcrvn - draws a series of curve segments 

rdr, rdri, rdrs, rdr2, rdr2i, rdr2s - relative draw 

readpi - returns values of specific pixels 

readRG - gets values of specific pixels 

readso - sets the source for pixels that various routines read 

rect, recti, rects - outlines a rectangular region 

rectco - copies a rectangle of pixels with an optional zoom 

rectf, rectfl, rectfs - fills a rectangular area 
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rectre - reads a rectangular array of pixels into CPU memory 

rectwr - draws a rectangular array of pixels into the frame buffer 

rectzo - specifies the zoom for rectangular pixel copies and writes 

resetl - controls the continuity of linestyles 

reshap - sets the viewport to the dimensions of the current graphics 
window 

RGBcol - sets the current color in RGB mode 

RGBcur - obsolete routine 

RGBmod - sets a rendering and display mode that bypasses the color 
map 

RGBran - obsolete routine 

RGBwri - grants write access to a subset of available bitplanes 

ringbe - rings the keyboard bell 

rmv, rmvi, rmvs, rmv2, rmv2i, rmv2s - relative move 

rotate, rot - rotate graphical primitives 

rpatch - draws a rational surface patch 

rpdr, rpdri, rpdrs, rpdr2, rpdr2i, rpdr2s - relative polygon draw 

rpmv, rpmvi, rpmvs, rpmv2, rpmv2i, rpmv2s - relative polygon 
move 

sbox, sboxi, sboxs - draw a screen-aligned rectangle 

sboxf, sboxfi, sboxfs - draw a filled screen-aligned rectangle 

scale - scales and mirrors objects 

sclear - clear the stencil planes to a specified value 

scrbox - control the screen box 

screen - map world space to absolute screen coordinates 

scrmas - defines a rectangular screen clipping mask 

scrnat - attaches the input focus to a screen 
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scrnse - selects the screen upon which new windows are placed 

scrsub - subdivide lines and polygons to a screen-space limit 

setbel - sets the duration of the beep of the keyboard bell 

setcur - sets the cursor characteristics 

setdbl - sets the lights on the dial and button box 

setdep - obsolete routine 

setlin - selects a linestyle pattern 

setmap - selects one of the small color maps provided by multimap 
mode 

setmon - sets the monitor type 

setnur - sets a property for the display of trimmed NURBS surfaces 

setpat - selects a pattern for filling polygons and rectangles 

setpup - sets the display characteristics of a given pop up menu entry 

setsha - obsolete routine 

setval - assigns an initial value and a range to a valuator 

setvid - set video hardware registers 

shadem - selects the shading model 

shader - obsolete routine 

single - writes and displays all bitplanes 

smooth - obsolete routine 

spclos - obsolete routine 

splf, splfi, splfs, splf2 ? splf2i, splf2s - draws a shaded filled polygon 

stenci - alter the operating parameters of the stencil 

stensi - specify the number of bitplanes to be used as stencil planes 

stepun - specifies that a graphics window change size in discrete steps 

strwid - returns the width of the specified text string 
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subpix - controls the placement of point, line, and polygon vertices 

swapbu - exchanges the front and back buffers of the normal frame- 
buffer 

swapin - defines a minimum time between buffer swaps 

swaptm - toggles the triangle mesh register pointer 

swinop - creates a graphics subwindow 

swrite - specify which stencil bits can be written 

t2d, t2f, t2i, t2s - specify a texture coordinate 

tevbin - selects a texture environment 

tevdef - defines a texture mapping environment 

texbin - selects a texture function 

texdef - convert a 2-dimensional image into a texture 

texgen - specify automatic generation of texture coordinates 

textco - sets the color of text in the textport 

textin - initializes the textport 

textpo - positions and sizes the textport 

tie - ties two valuators to a button 

tpon, tpoff- control the visibility of the textport 

transl - translates graphical primitives 

underl - allocates bitplanes for display of underlay colors 

unqdev - disables the specified device from making entries in the event 
queue 

v2d, v2f, v2i, v2s, v3d, v3f, v3i, v3s, v4d, v4f, v4i, v4s - transfers a 2- 
D, 3-D, or 4-D vertex to the graphics pipe 

videoc - initiates a command transfer sequence on an optional video 
peripheral 

viewpo - allocates an area of the window for an image 
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winatt - obsolete routine 

winclo - closes the identified graphics window 

wincon - binds window constraints to the current window 

windep - measures how deep a window is in the window stack 

window - defines a perspective projection transformation 

winget - returns the identifier of the current graphics window 

winmov - moves the current graphics window by its lower-left corner 

winope - creates a graphics window 

winpop - moves the current graphics window in front of all other win- 
dows 

winpos - changes the size and position of the current graphics window 
winpus - places the current graphics window behind all other windows 
winset - sets the current graphics window 
wintit - adds a title bar to the current graphics window 
wmpack - specifies RGBA writemask with a single packed integer 
writem - grants write permission to bitplanes 
writep - paints a row of pixels on the screen 
writeR - paints a row of pixels on the screen 

xfpt, xfpti, xfpts, xfpt2, xfpt2i ? xfpt2s, xfpt4, xfpt4i, xfpt4s - multi- 
plies a point by the current matrix in feedback mode 

zbuffe - enable or disable z-buffer operation in the current framebuffer 

zclear - initializes the z-buffer of the current framebuffer 

zdraw - enables or disables drawing to the z-buffer 

zfunct - specifies the function used for z-buffer comparison by the 
current framebuffer 

zsourc - selects the source for z-buffering comparisons 

zwrite - specifies a write mask for the z-buffer of the current frame- 
buffer 
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NAME 

acbuf - operate on the accumulation buffer 

FORTRAN SPECIFICATION 

subroutine acbuf(op, value) 
integer*4 op 
real value 

PARAMETERS 

op expects one of six symbolic constants: 

ACCLEAR: The red, green, blue, and alpha accumulation 
buffer contents are all set to value (rounded to the nearest 
integer), value is clamped to the range of a 16-bit signed integer. 

ACACCUMULATE: Pixels are taken from the current readso 
bank (front, back, or zbuffer). Their red, green, blue, and alpha 
components are each scaled by value. The resulting 16- 
bit/component pixels are added to the pixels already present in 
the accumulation buffer. The range of value is -255.996 through 
255.996. Arguments outside this range are clamped to it. Accu- 
mulated values are NOT clamped to the signed 16-bit range of 
the accumulation buffer. Thus overflow is avoided only by limit- 
ing the range of accumulation operations. 

ACCLEARACCUMULATE: An efficient combination com- 
mand whose effect is to first clear the accumulation buffer con- 
tents to zero, then add as per AC_ACCUMULATE. Ranges and 
clamping are as per AC_ACCUMULATE. 

ACRETURN: Pixels are taken from the accumulation buffer. 
Their red, green, blue, and alpha components are each scaled by 
value. The resulting 8-bit/component pixels are then written to 
the currently enabled drawing buffers (front, back, or zbuffer). 
All special pixel operations (zbuffer, blendftmction, logicop, 
stencil, texture mapping, etc.) are ignored during this transfer. 
Destination values are simply replaced. The operation is limited 
by the current viewport and screenmask, however. The range of 
value is 0.0 through 1.0. Arguments outside this range are 
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clamped to it. After being scaled by value, color components are 
clamped to the range through 255 before being written to the 
enabled drawing buffers. 

ACJVIULT: The red, green, blue, and alpha components of each 
accumulation buffer pixel are scaled by value. 

AC_ADD: value is added to each red, green, blue, and alpha 
component of each pixel in the accumulation buffer. 

value expects a float point value, op determines how value is used. 



SEE ALSO 

acsize, drawmo, subpix, somas 



c 



DESCRIPTION 

The accumulation buffer is a bank of 64-bit pixels, 16 bits each for red, 
green, blue, and alpha, that is mapped 1-to-l with screen pixels. Pixel 
images stored in the normal framebuffer (typically generated from 
geometric data) can be added to the accumulation buffer. These pixels 
are scaled during the transfer by a floating-point value (of limited range 
and resolution). Later, the accumulated image can be returned to the 
normal frame buffer, again while being scaled. 

Effects such as antialiasing (of points, lines, and polygons), motion- 
blur, and depth-of-field can be created by accumulating images gen- I 
erated with different transformation matrixes. Predictable effects are ^ 
possible only when subpixel mode is TRUE (see subpixel). 

readso mode is shared with other pixel read operations, including Irectr 
and rectco. rectzo however, has no effect on accumulation operation. 

All accumulation buffer operations are limited to the area of the current 
screenmask, which itself is limited to the current viewport. 

The accumulation buffer is a part of the normal framebuffer. acbuf 
should be called only while draw mode is NORMAL, and while the 
normal framebuffer is in RGB mode. 



c 
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NOTES 

An error is reported, and no action is taken, if accumulate is called while 
acsize is zero. 
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NAME 

acsize - specify the number of bitplanes per color component in the 
accumulation buffer 

FORTRAN SPECIFICATION 

subroutine acsize(planes) 
integer*4 planes 

PARAMETERS 

planes specifies the number of bitplanes to be reserved for each color 
component in the accumulation buffer. Accepted values are 
(default) and 16. 

DESCRIPTION 

Rendered images are accumulated (see acbuf) into a framebuffer with 

more than 8 bits per color component, acsize specifies the size of the 

accumulation buffer. You must call gconfi after acsize to activate the 

new size specification. 

By default the accumulation buffer size is zero, meaning that images 

cannot be accumulated. 

The 16-bit per component accumulation buffer is signed; it therefore 

supports accumulated values in the range -32768 through 32767. 

SEE ALSO 

acbuf, drawmo, gconfi 

NOTE 

This routine is available only in immediate mode. 

The accumulation buffer is available only in the normal framebuffer. 

acsize should be called only while draw mode is NORMAL. 

IRIS-4D G, GT, and GTX models, and the Personal Iris, do not support f 
the accumulation buffer. Use getgde to determine what support is avail- V 
able for accumulation buffering. 
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NAME 

addtop - adds items to an existing pop-up menu 

FORTRAN 77 SPECIFICATION 

subroutine addtop(pup, str, length, arg) 
integer*4 pup 
character*(*) str 
integer*4 length, arg 

PARAMETERS 

pup expects the menu identifier of the menu to which you want to 
add. The menu identifier is the returned function value of the 
menu creation call to newpup. 

str expects the variable that contains the text that you want to add 
as a menu item. In addition, you have the option of pairing an 
"item type" flag with each menu item. There are seven menu 
item type flags: 

%t marks item text as the menu title string. 

%F invokes a routine for every selection from this menu 
except those marked with a %n. You must specify the 
invoked routine in the arg parameter. The value of the 
menu item is used as a parameter of the executed rou- 
tine. Thus, if you select the third menu item, the system 
passes 3 as a parameter to the function specified by %F. 

%f invokes a routine when this particular menu item is 
selected. You must specify the invoked routine in the 
arg parameter. The value of the menu item is passed as 
a parameter of the routine. Thus, if you select the third 
menu item, the system passes 3 as a parameter to the 
routine specified by %f. If you have also used the %F 
flag within this menu, then the result of the %f routine 
is passed as a parameter of the %F routine. 
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%1 adds a line under the current entry. You can use this as 
a visual cue to group like entries together. 

%m pops up a menu whenever this menu item is selected. 
You must provide the menu identifier of the new menu 
in the arg parameter. 

%n like %f, this flag invokes a routine when the user selects 
this menu item. However, %n differs from %f in that it 
ignores the routine (if any) specified by %F. The value 
of the menu item is passed as a parameter of the exe- 
cuted routine. Thus, if you select the third menu item, 
the system passes 3 as a parameter to the function 
specified by %f. 

%xn assigns a numeric value to this menu item. This values 
overrides the default position-based value assigned to 
this menu item (e.g., the third item is 3). You must 
enter the numeric value as the n part of the text string. 
Do not use the arg parameter to specify the numeric 
value. 

NOTE: If you use the vertical bar delimiter, T, you can specify r 
multiple menu items in a text string. However, because there is ^ 
only one arg parameter, the text string can contain no more than 
one item type that references the arg parameter. 

length expects the length of the string pointed to by the str parameter. 

arg expects the command or submenu that you want to assign to the 
menu item. You can have only one arg parameter for each call 
to addtop. If the arg parameter is not needed, use as a place 
holder. 

DESCRIPTION 

addtop adds items to the bottom of an existing pop-up menu. You can 
build a menu by using a call to newpup to create a menu, followed by a 
call to addtop for each menu item that you want to add to the menu. To 
activate and display the menu, submit the menu to dopup. 
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EXAMPLE 

This example creates a menu with a submenu: 

submenu = newpupO 

call addtop (submen, ''rotate %f ' , 9, dorota) 

call addtop ( submen , 'translate %f ' , 12, dotran) 

call addtop (submen, 'scale %f , 8, doscal) 

menu = newpup ( ) 

call addtop(menu, 'sample %t' , 9, 0) 

call addtop (menu, < 'persp' , 5, 0) 

call addtop (menu, 'xform %m' , 8, submenu) 

call addtop(menu, 'greset %f ' , 9, greset) 

Because neither the "sample" menu title nor the "persp" menu item refer 
to the arg parameter, you can group "sample", "persp", and "xform" in a 
single call. 

call addtop(menu, 'sample %t | persp | xform %m' , 28, 
+ submenu) 

SEE ALSO 

dopup, freepup, newpup 

NOTES 

This routine is available only in immediate mode. 

When using the Distributed Graphics Library (DGL), you can not call 
other DGL routines within a function that is called by a popup menu, i.e. 
a function given as the argument to a %f or %F item type. 
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NAME 

afunct - specify alpha test function 

FORTRAN SPECIFICATION 

subroutine afunct(ref, func) f 

integer*4 ref, func ^ 

PARAMETERS 

ref expects a reference value with which to compare source alpha at 
each pixel. This value should be in the range through 255. 

func expects one of two flags specifying the alpha comparison func- 
tion: AFNOTE and AFALWA (the default). 

DESCRIPTION 

afunct makes the drawing of pixels conditional on the relationship of 
the incoming alpha value to a reference constant value. It is typically 
used to avoid updating either the color or the z field of a framebuffer 
pixel when the incoming pixel is completely transparent. Arguments ref 
and func specify the conditions under which the pixel will be drawn. 
The incoming (source) alpha value is compared to ref with function 
func, and if the comparison passes, the incoming pixel is drawn (condi- 
tional on subsequent z-buffer tests). Thus afunct can be called with 
arguments ? AFNOTE 

to defeat drawing of completely transparent pixels. This assumes that 
incoming alpha is proportional to pixel coverage, as it is when either 
points or linesm is being used. 

afunct testing follows scan conversion, texture mapping, and stencil 
operation, but preceeds all other pixel tests. Thus, if the test fails, nei- 
ther the color nor zbuffer contents will be modified, afunct operates on 
all pixel writes, including those resulting from the scan conversion of 
points, lines, and polygons, and from pixel write and copy operations. 
afunct does not affect screen clear operation, however. 
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SEE ALSO 
blendf 



NOTES 



IRIS-4D G, GT, and GTX models, and the Personal Iris, do not support 
afunct. Use getgde to determine what support is available for afunct. 



BUGS 



On IRIS-4D VGX models afunct cannot be enabled while stenci is 
being used. Also, ref must be 0. 
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NAME 

arc, arci, arcs - draw a circular arc 

FORTRAN 77 SPECIFICATION 

subroutine arc(x, y, radius, stang, endang) 
real x, y, radius 
integer*4 stang, endang 

subroutine arci(x, y, radius, stang, endang) 
integer*4 x, y, radius, stang, endang 

subroutine arcs(x, y, radius, stang, endang) 
integer*2 x, y, radius 
integer*4 stang, endang 

All of the routines named above are functionally the same. They differ 
only in the type assignments of their parameters. 

PARAMETERS 

x expects the x coordinate of the center of the arc. The center of 

the arc is the center of the circle that would contain the arc. 

y expects the y coordinate of the center of the arc. The center of 

the arc is the center of the circle that would contain the arc. 

radius expects the length of the radius of the arc. The radius of the 
arc is the radius of the circle that would contain the arc. 

stang expects the measure of the start angle of the arc. The start 
angle of the arc is measured from the positive x-axis. 

endang expects the measure of the end angle of the arc. The end angle 
of the arc is measured from the positive x-axis. 

DESCRIPTION 

arc draws an unfilled circular arc in the x-y plane (z = 0). To draw an arc 
in a plane other than the x-y plane, define the arc in the x-y plane and 
then rotate or translate the arc. I 
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An arc is drawn as a sequence of line segments, and therefore inherits all 
properties that affect the drawing of lines. These include the current 
color, writemask, line width, stipple pattern, shade model, line antialias- 
ing mode, and subpixel mode. The stipple pattern is initialized to bit 
zero of the current linestyle before the arc is drawn, then shifted con- 
tinuously through the segments of the arc. 

An arc is defined in terms of the circle that contains it. All references to 
the radius and center of the arc refer to the radius and center of the circle 
that contains the arc. The angle swept out by the arc is the angle from 
the start angle counter-clockwise to the end angle. 

The start and end angles are defined relative to the positive x-axis. (To 
speak more precisely, because the arc might not be centered on the ori- 
gin, the start and end angles are defined relative to the right horizontal 
radius of the circle containing the arc). Positive values for an angle 
indicate a counter-clockwise rotation from the horizontal. Negative 
values indicate a clockwise rotation from the horizontal. 

The basic unit of angle measure is a tenth of a degree. The value 900 
indicates an angle of 90 degrees in a counter-clockwise direction from 
the horizontal. Thus, an arc that spans from a start angle of 10 degrees 
(stang = 100) to an end angle of 5 degrees (endang - 50) is almost a 
complete circle. 

After arc executes, the graphics position is undefined. 

SEE ALSO 

arcf, bgnclo, circ, crvn, linewi, linesm, lsrepe, scrsub, setlin, shadem, 
subpix 



BUGS 



When the line width is greater than 1, small notches will appear in arcs, 
because of the way wide lines are implemented. 
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NAME 

arcf, arcfi, arcfs - draw a filled circular arc 

FORTRAN 77 SPECIFICATION 

subroutine arcf(x, y, radius, stang, endang) 
real x, y, radius 
integer*4 stang, endang 

subroutine arcfi(x, y, radius, stang, endang) 
integer*4 x, y, radius, stang, endang 

subroutine arcfs(x, y, radius, stang, endang) 
integer*! x, y, radius 
integer*4 stang, endang 

All of the routines named above are functionally the same. They differ 
only in the type assignments of their parameters. 



c 



PARAMETERS 



radius 



expects the x coordinate of the center of the filled arc. The 
center of the filled arc is the center of the circle that would 
contain the arc. 

expects the y coordinate of the center of the filled arc. The 
center of the filled arc is the center of the circle that would 
contain the arc. 

expects the length of the radius of the filled arc. The radius of 
the filled arc is the radius of the circle that would contain the 
filled arc. 



stang expects the measure (in tenths of a degree) of the start angle of 
the filled arc. The start angle of the filled arc is measured rela- 
tive to the positive x-axis. 

endang expects the measure (in tenths of a degree) of the end angle of 
the filled arc. The end angle of the filled arc is measured rela- 
tive to the positive x-axis. 
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DESCRIPTION 

arcf draws a filled circular arc in the x-y plane (z = 0). The filled area is 
bound by the arc and by the start and end radii. To draw an arc in a 
plane other than the x-y plane, define the arc in the x-y plane and then 
rotate or translate the arc. 

An arc is drawn as a single polygon, and therefore inherits all properties 
that affect the drawing of polygons. These include the current color, 
writemask, fill pattern, shade model, polygon antialiasing mode, 
polygon scan conversion mode, and subpixel mode. Front-face and 
back-face elimination work correctly with filled arcs, which are front- 
facing when viewed from the positive z half-space. 

A filled arc is defined in terms of the circle that contains it. All refer- 
ences to the radius and the center of the filled arc refer to the radius and 
center of the circle that contains the filled arc. The angle swept out by 
the filled arc is the angle from the start angle counter-clockwise to the 
end angle. 

The start and end angles are defined relative to the positive x-axis. (To 
speak more precisely, because the arc might not be centered on the ori- 
gin, the start and end angles are defined relative to the right horizontal 
radius of the circle containing the arc). Positive values for an angle indi- 
cate a counter-clockwise rotation from the horizontal. Negative values 
indicate a clockwise rotation from the horizontal. 

The basic unit of angle measure is a tenth of a degree. The value 900 
indicates an angle of 90 degrees in a counter-clockwise direction from 
the horizontal. Thus, a filled arc that spans from a start angle of 10 
degrees (stang = 100) to an end angle of 5 degrees (endang = 50) is 
almost a complete filled circle. 

After arcf executes, the graphics position is undefined. 

SEE ALSO 

arc, backfa, bgnpol, circf, frontf, polymo, polysm, scrsub, setpat, 
shadem, subpix 
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NAME 

attach - attaches the cursor to two valuators 

FORTRAN 77 SPECIFICATION 

subroutine attach(vx, vy) I 

integer*4 vx, vy 

PARAMETERS 

vx expects the valuator device number for the device that controls the 
horizontal location of the cursor. By default, vx is MOUSEX. 

vy expects the valuator device number for the device that controls the 
vertical location of the cursor. By default, vy is MOUSEY. 

DESCRIPTION 

attach attaches the cursor to the movement of two valuators. Both vx 
and vy are valuator device numbers. (See Appendix A, Valuators, for a 
list of device numbers.) The values at vx and vy determine the cursor 
position in screen coordinates. Every time the values at vx or vy change, f 
the system redraws the cursor at the new coordinates. V 

SEE ALSO 

noise, tie 

NOTE 

This routine is available only in immediate mode. 
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NAME 

backbu, frontb - enable and disable drawing to the back or front buffer 

FORTRAN 77 SPECIFICATION 

subroutine backbu(b) 
logical b 

subroutine frontb(b) 
logical b 

PARAMETERS 

h expects either .TRUE, or .FALSE.. 

.TRUE, enables updating in the back/front bitplane buffer. 
.FALSE, turns off updating in the back/front bitplane buffer. 

DESCRIPTION 

The IRIS framebuffer is divided into four separate GL framebuffers: 
pop-up, overlay, underlay, and normal. Three of these framebuffers, 
overlay, underlay, and normal, can be configured in double buffer mode. 
When so configured, a framebuffer includes two color bitplane buffers: 
one visible bitplane buffer, called the front buffer, and one non-visible 
bitplane buffer, called the back buffer. The commands swapbu and 
mswapb interchange the front and back buffer assignments. 

By default, when a framebuffer is configured in double buffer mode, 
drawing is enabled in the back buffer, and disabled in the front buffer. 
frontb and backbu enable and disable drawing into the front and back 
buffers, allowing the default to be overriden. Its is acceptable to enable 
neither front nor back, either front or back, or both front and back simul- 
taneously. Note, for example, that z-buffer drawing continues to update 
the z-buffer with depth values when neither the front buffer nor the back 
buffer is enabled for drawing. 

frontb and backbu state is maintained separately for each of the over- 
lay, underlay, and normal framebuffers. Calls to these routines affect 
the framebuffer that is currently active, based on the current drawmode. 
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backbu is ignored when the currently active framebuffer is in single 
buffer mode, frontb is also ignored when the currently active frame- 
buffer is in single buffer mode, unless zdraw is enabled for that frame- 
buffer (see zdraw). 

After each call to gconfi, backbu is enabled and frontb is disabled. 

SEE ALSO 

drawmo, double, getbuf, gconfi, single, swapbu, zdraw 

NOTE 

Only VGX graphics support double buffer operation in the overlay and 
underlay framebuffers. 
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NAME 

backfa - turns backfacing polygon removal on and off 

FORTRAN 77 SPECIFICATION 

subroutine backfa(b) 
logical b 

PARAMETERS 

b expects either .TRUE, or .FALSE.. 

.TRUE, suppresses the display of backfacing filled polygons. 
.FALSE, allows the display of backfacing filled polygons. 

DESCRIPTION 

backfa allows or suppresses the display of backfacing filled polygons. 
If your programs represent solid objects as collections of polygons, you 
can use this routine to remove hidden surfaces. This routine works best 
for simple convex objects that do not obscure other objects. 

A backfacing polygon is defined as a polygon whose vertices are in 
clockwise order in screen coordinates. When backfacing polygon remo- 
val is on, the system displays only polygons whose vertices are in 
counter-clockwise order. For complicated objects, this routine alone 
may not remove all hidden surfaces. To remove hidden surfaces for 
more complicated objects or groups of objects, your routine needs to 
check the relative distances of the object from the viewer (z values). 
(See * 'Hidden Surface Removal' ' in the Graphics Library Programming 
Guide.) 

SEE ALSO 

zbuffe 

NOTES 

Matrices that negate coordinates, such as scale(-1.0, 1.0, 1.0), reverse 
the directional order of a polygon's points and can cause backfa to do 
the opposite of what is intended. 
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On IRIS-4D B and G models backfa does not work well when a 
polygon shrinks to the point where its vertices are coincident. Under 
these conditions, the routine cannot determine the orientation of the 
polygon and so displays the polygon by default 
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NAME 

bbox2, bbox2i, bbox2s - culls and prunes to bounding box and 
minimum pixel radius 

FORTRAN 77 SPECIFICATION 

subroutine bbox2(xmin, ymin, xl, yl, x2, y2) 
integer*4 xmin, ymin 
real xl, yl, x2, y2 

subroutine bbox2i(xmin, ymin, xl, yl, x2, y2) 
integer*4 xmin, ymin, xl, yl, x2, y2 

subroutine bbox2s(xmin, ymin, xl, yl, x2, y2) 
integer*4 xmin, ymin 
integer*2 xl, yl, x2, y2 

All of the above routines are functionally the same. They differ only in 
the declaration types of their parameters. 

PARAMETERS 

xmin expects the width, in pixels, of the smallest displayable feature. 

ymin expects the height, in pixels, of the smallest displayable feature. 

xl expects the x coordinate of a corner of the bounding box. 

yl expects the y coordinate of a corner of the bounding box. 

x2 expects the x coordinate of a corner of the bounding box. The 
corner referenced by this parameter must be diagonally opposite 
the corner referenced by the xl and yl parameters. 

y2 expects the y coordinate of a corner of the bounding box. The 
corner referenced by this parameter must be diagonally opposite 
the corner referenced by the xl and yl parameters. 

DESCRIPTION 

bbox2 performs the graphical functions known as culling and pruning. 
Culling prevents the system from drawing objects that are less than the 
minimum feature size (xmin and ymin). Pruning prevents the system 
from drawing objects that lie completely outside the viewport. 
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To determine whether or not to cull an object, bbox2 tests whether or 
not the display of a rectangle the size of the bounding box is smaller 
than the minimum feature size. To determine whether or not to prune an 
object, bbox2 tests whether or not the bounding box is competely out- 
side the viewport. 

Call bbox2 within the definition for an object, just after the call to 
makeob. If the object must be pruned or culled, the remainder of the 
object definition is ignored. 

SEE ALSO 
makeob 

NOTES 

This routine does not function in immediate mode. 

This routine is not a free test. If you use bbox2 too freely, your perfor- 
mance can suffer. Reserve bbox2 for complicated object definitions 
only. 
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NAME 

bgnclo, endclo - delimit the vertices of a closed line 

FORTRAN 77 SPECIFICATION 
subroutine bgnclo 
subroutine endclo 

PARAMETERS 

none 

DESCRIPTION 

bgnclo marks the start of a group of vertex routines that you want inter- 
preted as points on a closed line. Use endclo to mark the end of the ver- 
tex routines that are part of the closed line. 

A closed line draws a line segment from one vertex on the list to the 
next vertex on the list. When the system reaches the end of the vertex 
list, it draws a line that connects the last vertex to the first vertex. All 
segments use the current linestyle, which is reset prior to the first seg- 
ment and continues through subsequent segments. To specify a vertex, 
use the v routine. 

Between bgnclo and endclo, you can issue only the following Graphics 
Library routines: c, color, cpack, Imbind, lmcolo, Imdef, n, RGBcol, t, 

and v. Within a closed line, you should use lmdef and Imbind only to 
respecify materials and their properties. If the color changes between a 
pair of vertices, the color of the line segment will be constant if the 
current shading model is FLAT and interpolated if the current shading 
model is GOURAU. In color map mode, the colors vary through the 
color map; to get reasonable results, the color map should contain a 
ramp. 

There is no limit to the number of vertices that can be specified between 
bgnclo and endclo. After endclo, the system draws a line from the final 
vertex back to the initial vertex, and the current graphics position is left 
undefined. 
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By default line vertices are forced to the nearest pixel center prior to 
scan conversion. Line accuracy is improved when this coercion is 
defeated with the subpix command. Subpixel vertex positioning is 
especially important when lines are scan converted with antialiasing 
enabled (see linesm). 

bgnclo/endclo are the same as bgnlin/endlin, except they connect the 
last vertex to the first. 

EXAMPLE 

The code fragment below draws the outline of a triangle. Lines use the 
current linestyle, which is reset prior to the first vertex and continues 
through all subsequent vertices. 

call bgnclo 
call v3f (vertl) 
call v3f (vert2) 
call v3f (vert3) 
call endclo 

SEE ALSO 

bgnlin, c, linesm, linewi, lsrepe, scrsub, setlin, shadem, subpix, v 

BUGS 

On the DRIS-4D B and G models, and on the Personal Iris without Turbo 
Graphics, if the color changes between a pair of vertices, the color of the 
line segment will be constant regardless of the current shading model. 

On the IRIS-4D GT and GTX models, if the color changes between a 
pair of vertices, the color of the line segment will be interpolated regard- 
less of the current shading model. 
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NAME 

bgnlin, endlin - delimit the vertices of a line 

FORTRAN 77 SPECIFICATION 
subroutine bgnlin 
subroutine endlin 

PARAMETERS 

none 

DESCRIPTION 

Vertices specified after bgnlin and before endlin are interpreted as end- 
points of a series of line segments. Use the v routine to specify a vertex. 
The first vertex connects to the second; the second connects to the third; 
and so on until the next-to-last vertex connects to the last one. The last 
vertex does not connect to the first vertex. Use bgnclo to connect the 
first and last points. All segments use the current linestyle, which is reset 
prior to the first segment and continues through subsequent segments. 

Between bgnlin and endlin, you can issue only the following Graphics 
Library routines: c, color, cpack, lmbind, Imcolo, lmdef, n, RGBcol, 
t, and v. lmdef and lmbind can be used to respecify only materials and 
their properties. If the color changes between a pair of vertices, the color 
of the line segment will be constant if the current shading model is 
FLAT and interpolated if the current shading model is GOURAU. In 
color map mode, the colors vary through the color map; to get reason- 
able results, the color map should contain a ramp. 

There is no limit to the number of vertices that can be specified between 
bgnlin and endlin. After endlin, the current graphics position is 
undefined. 

By default line vertices are forced to the nearest pixel center prior to 
scan conversion. Line accuracy is improved when this coercion is 
defeated with the subpix command. Subpixel vertex positioning is 
especially important when lines are scan converted with antialiasing 
enabled (see linesm). 
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SEE ALSO 

bgnclo, c, linesm, linewi, lsrepe, scrsub, setlin, shadem, subpix, v 

BUGS 

On the IRIS-4D B and G models, and on the Personal Iris without Turbo 
Graphics, if the color changes between a pair of vertices, the color of the 
line segment will be constant regardless of the current shading model. 

On the IRIS-4D GT and GTX models, if the color changes between a 
pair of vertices, the color of the line segment will be interpolated regard- 
less of the current shading model. 
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NAME 

bgnpoi, endpoi - delimit the interpretation of vertex routines as points 

FORTRAN 77 SPECIFICATION 
subroutine bgnpoi 
subroutine endpoi 

PARAMETERS 

none 

DESCRIPTION 

bgnpoi marks the beginning of a list of vertex routines that you want 
interpreted as points. Use the endpoi routine to mark the end of the list. 
For each vertex, the system draws a one-pixel point into the frame 
buffer. Use the v routine to specify a vertex. 

Between bgnpoi and endpoi, you can issue only the following Graphics 
Library routines: c, color, cpack, lmbind, Imcolo, lmdef, n, RGBcol, t, 
and v. Use lmdef and lmbind to respecify only materials and their pro- 
perties. 

There is no limit to the number of vertices that can be specified between 
bgnpoi and endpoi. 

By default points are forced to the nearest pixel center prior to scan 
conversion. This coercion is defeated with the subpix command. Sub- 
pixel point positioning is important only when points are scan converted 
with antialiasing enabled (see pntsmo). 

After endpoi, the current graphics position is the most recent vertex. 

SEE ALSO 

c, pntsmo, subpix, v 
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SEE ALSO 

backfa, c, concav, frontf, polymo, polysm, scrsub, setpat, shadem, sub- 
pix,v 
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NAME 

bgnpol, endpol - delimit the vertices of a polygon 

FORTRAN 77 SPECIFICATION 
subroutine bgnpol 
subroutine endpol 

PARAMETERS 

none 

DESCRIPTION 

Vertices specified after bgnpol and before endpol form a single 
polygon. The polygon can have no more than 256 vertices. Use the v 
subroutine to specify a vertex. Self-intersecting polygons (other than 
four-point bowties) may render incorrectly. Likewise, concave 
polygons may not render correctly if you have not called 
concav(.TRUE.). 

Between bgnpol and endpol, you can issue only the following Graphics I 
Library subroutines: c, color, cpack, Imbind, Imcolo, Imdef, n, 
RGBcol, t, and v. Use Imdef and Imbind to respecify only materials 
and their properties. 

By default polygon vertices are forced to the nearest pixel center prior to 
scan conversion. Polygon accuracy is improved when this coercion is 
defeated with the subpix command. Subpixel vertex positioning is 
especially important when polygons are scan converted with antialiasing 
enabled (see polysm). 

After endpol, the current graphics position is i^ndefined. 
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NOTES 

If you want to use the backfa or frontf routines, specify the vertices in 
counter-clockwise order. 

Although calling concav(.TRUE.) will guarantee that all polygons will 
be drawn correctly, on the IRIS-4D B and G models, and on the Per- 
sonal Iris, doing so cause their performance to be degraded. 
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NAME 

bgnqst, endqst - delimit the vertices of a quadrilateral strip 

FORTRAN SPECIFICATION 
subroutine bgnqst 
subroutine endqst 

DESCRIPTION 

Vertices specified between bgnqst and endqst are used to define a strip 
of quadrilaterals. The graphics pipe maintains three vertex registers. 
The first, second, and third vertices are loaded into the registers, but no 
quadrilateral is drawn until the system executes the fourth vertex rou- 
tine. Upon executing the fourth vertex routine, the system draws a qua- 
drilateral through the vertices, then replaces the two oldest vertices with 
the third and fourth vertices. 

For each new pair of vertex routines, the system draws a quadrilateral 
through two new vertices and the two older stored vertices, then replaces 
the older stored vertices with the two new vertices. 

Between bgnqst and endqst you can issue the following Graphics 
Library routines: c, color, cpack, Imbind, Imcolo, Imdef, n, RGBcol, 
t, and v. Use Imdef and Imbind only to respecify materials and their 
properties. 

If you want to use backfa, you should specify the vertices of the first 
quadrilateral in counter-clockwise order. All quadrilaterals in the strip 
have the same rotation as the first quadrilateral in a strip, so that back- 
facing works correctly. 

There is no limit to the number of vertices that can be specified between 
bgnqst and endqst. The result is undefined, however, if an odd number 
of vertices are specified, or if fewer than four vertices are specified. 

By default quadrilateral vertices are forced to the nearest pixel center 
prior to scan conversion. Quadrilateral accuracy is improved when this 
coercion is defeated with the subpix command. Subpixel vertex posi- 
tioning is especially important when quadrilaterals are scan converted 
with antialiasing enabled (see polysm). 
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After endqst the current graphics position is undefined. 

EXAMPLE 

For example, the code sequence: 

call bgnqst 
call v3f (zero) 
call v3f (one) 
call v3f (two) 
call v3f (three) 
call v3f (four) 
call v3f (five) 
call v3f (six) 
call v3f (seven) 
call endqst 

draws three quadrilaterals: (0,1,2,3), (2,3,4,5), and (4,5,6,7). Note that 
the vertex order required by quadrilateral strips matches the order 
required by the equivalent triangle mesh. The vertices above, when 
places between bgntme and endtme calls, draws six triangles: (0,1,2), 
(1,2,3), (2,3,4), (3,4,5), (4,5,6), and (5,6,7). 

SEE ALSO 

backfa, c, concav, frontf, polymo, polysm, scrsub, setpat, shadem, sub- 
pix,v 



NOTE 



IRIS-4D G, GT, and GTX models, and the Personal Iris, do not support 
quadrilateral strips. Use getgde to determine whether quadrilateral 
strips are supported. 

IRIS-4D VGX models use vertex normals to improve the shading qual- 
ity of quadrilaterals, regardless of whether lighting is enabled. 



Version 3.0 -2- April 1990 



bgnsur Graphics Reference, FORTRAN bgnsur 

NAME 

bgnsur, endsur - delimit a NURBS surface definition 

FORTRAN 77 SPECIFICATION 

subroutine bgnsur | 

subroutine endsur 

PARAMETERS 

none 

DESCRIPTION 

Use bgnsur to mark the beginning of a NURB S (Non-Uniform Rational 
B-Spline) surface definition. After you call bgnsur, call the routines that 
define the surface and that provide the trimming information. To mark 
the end of a NURBS surface definition, call endsur. 



Within a NURBS surface definition (between bgnsur and endsur), you 
may use only the following Graphics Library subroutines: nurbss, 
bgntri, endtri, nurbsc, and pwlcur. The NURBS surface definition 
must consist of exactly one call to nurbss to define the shape of the sur- 
face. In addition, this call may be preceeded by calls to nurbss that 
specify how texture and color parameters vary across the surface. The 
call(s) to nurbss may be followed by a list of one or more trimming 
loop definitions (to define the boundaries of the surface). Each trim- 
ming loop definition consists of one call to bgntri, one or more calls to 
either pwlcur or nurbsc, and one call to endtri. 

The system renders a NURBS surface as a polygonal mesh, and calcu- 
lates normal vectors at the corners of the polygons within the mesh. 
Therefore, your program should specify a lighting model if it uses 
NURBS surfaces. If your program uses no lighting model, all the 
interesting surface information is lost. When using a lighting model, 
use lmdef and Imbind to define or modify materials and their proper- 
ties. 



c 



( 
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EXAMPLE 

The following code fragment draws a NURBS surface trimmed by two 
closed loops. The first closed loop is a single piecewise linear curve 
(see pwlcur), and the second closed loop consists of two NURBS curves 
(see nurbsc), joined end to end: 



call bgnsur 




call nurbss(. „ .) 




call bgntri 




call pwlcur (. . 


.) 


call endtri 




call bgntri 




call nurbsc ( . . 


.) 


call nurbsc ( . . 


.) 


call endtri 




call endsur 





SEE ALSO 

nurbss, bgntri, nurbsc, pwlcur, setnur, getnur 
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NAME 

bgntme, endtme - delimit the vertices of a triangle mesh 

FORTRAN 77 SPECIFICATION 

subroutine bgntme | 

subroutine endtme 

PARAMETERS 

none 

DESCRIPTION 

Vertices specified between bgntme and endtme are used to define a 
mesh of triangles. The graphics pipe maintains two vertex registers. 
The first and second vertices are loaded into the registers, but no triangle 
is drawn until the system executes the third vertex routine. Upon execut- 
ing the third vertex routine, the system draws a triangle through the ver- 
tices, then replaces the older of the register vertices with the third ver- 
tex. 



For each new vertex routine, the system draws a triangle through the 
new vertex and the stored vertices, then (by default) replaces the older 
stored vertex with the new vertex. If you want the system to replace the 
more recent of the stored vertices, call swaptm prior to calling v. 

Between bgntme and endtme you can issue the following Graphics 
Library routines: c, color, cpack, Imbind, Imcolo, Imdef, n, RGBcol, 
swaptm, t, and v. Use Imdef and Imbind only to respecify materials 
and their properties. 

If you want to use backfa, you should specify the vertices of the first tri- 
angle in counter-clockwise order. All triangles in the mesh have the 
same rotation as the first triangle in a mesh so that backfacing works 
correctly. 

There is no limit to the number of vertices that can be specified between 
bgntme and endtme. 



c 



c 
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By default triangle vertices are forced to the nearest pixel center prior to 
scan conversion. Triangle accuracy is improved when this coercion is 
defeated with the subpix command. Subpixel vertex positioning is 
especially important when triangles are scan converted with antialiasing 
enabled (see polysm). 

After endtme the current graphics position is undefined. 

EXAMPLE 

For example, the code sequence: 

call bgntme 
call v3f (zero) 
call v3f (one) 
call v3f (two) 
call v3f (three) 
call endtme 

draws two triangles, (zero,one,two) and (one,two,three), while the code 
sequence: 

bgntme 
v3f (zero) 
v3f(one) 
swaptm 
v3f (two) 
v3f (three) 
endtme 

draws two triangles, (zero,one,two) and (zero,two,three). There is no 
limit to the number of times that swaptmesh can be called. 

SEE ALSO 

backfa, c, concav, frontf, polymo, polysm, scrsub, setpat, shadem, sub- 
pix, swaptm, v 
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NAME 

bgntri, endtri - delimit a NURBS surface trimming loop 

FORTRAN 77 SPECIFICATION 

subroutine bgntri | 

subroutine endtri 

PARAMETERS 

none 

DESCRIPTION 

Use bgntri to mark the beginning of a definition for a trimming loop. 
Use endtri to mark the end of a definition for a trimming loop. A trim- 
ming loop is a set of oriented curves (forming a closed curve) that 
defines boundaries of a NURBS surface. You include these trimming 
loop definitions in the definition of a NURBS surface. 

The definition for a NURBS surface may contain many trimming loops. 
For example, if you wrote a definition for NURBS surface that resem- f 
bled a rectangle with a hole punched out, the definition would contain V 
two trimming loops. One loop would define the outer edge of the rec- 
tangle. The other trimming loop would define the hole punched out of 
the rectangle. The definitions of each of these trimming loops would be 
bracketed by a bgntri/endtri pair. 

The definition of a single closed trimming loop may consist of multiple 
curve segments, each described as a piecewise linear curve (see pwlcur) 
or as a single NURBS curve (see nurbsc), or as a combination of both 
in any order. The only Graphics library calls that can appear in a trim- 
ming loop definition (between a call to bgntri and a call to endtri) are 
pwlcur and nurbsc. 
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In the following code fragment, we define a single trimming loop that 
consists of one piecewise linear curve and two NURBS curves: 



call bgntri 




call pwlcur(. 


. -.) 


call nurbsc ( . 


. -) 


call nurbsc (. 


. •) 


call endtri 





The area of the NURBS surface that the system displays is the region in 
the domain to the left of the trimming curve as the curve parameter 
increases. Thus, the resultant visible region of the NURBS surface is 
inside for a counter-clockwise trimming loop and outside for a clock- 
wise trimming loop. So for the rectangle mentioned earlier, the trim- 
ming loop for the outer edge of the rectangle should run counter- 
clockwise, and the trimming loop for the hole punched out should run 
clockwise. 

If you use more than one curve to define a single trimming loop, the 
curve segements must form a closed loop (i.e, the endpoint of each 
curve must be the starting point of the next curve, and the endpoint of 
the final curve must be the starting point of the first curve). If the end- 
points of the curve are sufficiently close together but not exactly coin- 
cident, the system coerces the them to match. If the endpoints are not 
sufficiently close, the system generates an error message and ignores the 
entire trimming loop. 

If a trimming loop definition contains multiple curves, the direction of 
the curves must be consistent (i.e., the inside must be to the left of the 
curves). Nested trimming loops are legal as long as the curve orienta- 
tions alternate correctly. If no trimming information is given for a 
NURBS surface, the entire surface is drawn. 

SEE ALSO 

bgnsur, nurbss, nurbsc, pwlcur, setnur, getnur 
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NAME 

blanks - controls screen blanking 

FORTRAN 77 SPECIFICATION 

subroutine blanks(b) 
logical b 

PARAMETERS 



c 



h expects .TRUE, or .FALSE.. 

.TRUE, stops display and turns screen black. 
.FALSE, restores the display. 

DESCRIPTION 

blanks turns screen refresh on and off. It affects the screen on which 
the current window is displayed. 

NOTE s- 

This routine is available only in immediate mode. V 

SEE ALSO 
blankt 



() 
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NAME 

blankt - sets the screen blanking timeout 

FORTRAN 77 SPECIFICATION 

subroutine blankt(count) 
integer*4 count 

PARAMETERS 

count expects the number of graphics timer events after which to blank 
the current screen. The frequency of graphics timer events is 
returned by the getgde inquiry GDTIME. 

DESCRIPTION 

By default, a screen blanks (turns black) after the system receives no 
input for 10 minutes. This protects the monitor. Use blankt to change 
the amount of time the system waits before it blanks a screen. It affects 
the screen on which the current window is displayed. 

To calculate the value of count, simply multiply the desired blanking 
latency period (in seconds) by getgde(GDTIME). 

You can disable screen blanking by calling this routine with a count of 
zero. 

NOTE 

This routine is available only in immediate mode. 

SEE ALSO 

blanks, getgde 
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NAME 

blendf - computes a blended color value for a pixel 



FORTRAN 77 SPECIFICATION 

subroutine blendf(sfactr, dfactr) 
integer*4 sfactr, dfactr 



( 



PARAMETERS 

sfactr Expects a symbolic constant from the list below that identifies 
the blending factor by which to scale contribution from source 
pixel RGBA (red, green, blue, alpha) values. Blending factors 
use RGBA values converted to fractions of the maximum value 
255. To improve performance, conversion calculations are 
approximate. However, converts exactly to 0.0, and 255 con- 
verts exactly to 1.0. 



BFZERO 





BFONE 


1 


BFDC 


(destination RGBA)/255 


BFMDC 


1 - (destination RGBA)/255 


BFSA 


(source alpha)/255 


BFMSA 


1 - (source alpha)/255 


BFDA 


(destination alpha)/255 


BFMDA 


1 - (destination alpha)/255 


BFMINS 


mirt(BF_SA, BF_MDA) 



c 



dfactr Expects a symbolic constant from the list below that identifies 
the blending factor by which to scale contribution from destina- 
tion pixel RGBA values. 

BFZERO 

BFONE 1 

BFSC (source RGBA)/255 

BFMSC 1 - (source RGBA)/255 

BFSA (source alpha)/255 

BFMSA 1 - (source alpha)/255 



( 
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BFDA (destination alpha)/255 

BFMDA 1 - (destination alpha)/255 

DESCRIPTION 

In RGB mode, the system draws pixels using a function that blends the 
incoming (source) RGBA values with the RGBA values that are already 
in the framebuffer (the destination values). Most often, blending is sim- 
ple: the source RGBA values replace the destination RGBA values of 
the pixel. 

In some cases, however, simple replacement of framebuffer values is not 
appropriate. Two such cases are transparency and antialiasing. To be 
blended properly, transparent objects must be rendered back-to-front 
(i.e. drawn in order from the farthest object to the nearest object) with a 
blend function of (BFSA, BFMSA). As can be seen from the equations 
below, this function scales the incoming color components by the 
incoming alpha value, and scales the framebuffer contents by one minus 
the incoming alpha value. Thus incoming (source) alpha is correctly 
thought of as a material opacity, ranging from 1.0 (completely opaque) 
to 0.0 (completely transparent). Note that this transparency calculation 
does not require the presence of alpha bitplanes in the framebuffer. 

Suggestions for appropriate blend functions for antialiasing are given on 
the pntsmo and linesm manual pages. Other less obvious applications 
are also possible. For example, if the red component in the framebuffer 
is first cleared to all zeros, and then each primitive is drawn with red set 
to 1 and a blend function of (BFONE, BFONE), the red component of 
each pixel in the framebuffer will contain the count of the number of 
times that pixel was drawn. 

To determine the blended RGBA values of a pixel when drawing in 
RGB mode, the system uses the following functions: 

R destination = ™* (255, ((R source X sfdCtr) + (R destination X dfdCtr))) 
G destination = ™ n < 255 ' « G source X S f aCtr ) + ^destination X 4fa*r))) 
B destination = ™ n ( 255 ' « B source X ^C*0 + (B deslination X dfaCtr))) 
A destination = ™ n < 255 ' « A source X S f aCtr ) + ^destination X #«*■))) 
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When the blend function is set to (BFONE, BFZERO), the default 
values, the equations reduce to simple replacement: 

R = R 

destination source 

(~* p 1 

destination ~" source 

"R = "R 

destination source 

A = A 

destination source 

Fill rate may be increased substantially when blending is disabled in this 
manner. 

Polygon antialiasing (see polysm) is sometimes optimized when the 
blendfunction (BFMINS, BFONE) is used. Source factor BFMINS, 
which should be used only with destination factor BFONE, has the side 
effect of slightly modifying the blending arithmetic: 

R destination = min ( 255 > ^source X tf mtr ) + R destinati oo» 
destination = TO * < 255 > ^source X tf™*) + G destination)) 
B destination = mifl < 255 > ^source X &**) + B destinati on» 
^destination = s f actr + ^destination 

This special blend function accumulates pixel contributions until the 
pixel is fully specified, then allows no further changes. Destination 
alpha bitplanes, which must be present for this blend function to operate 
correctly, store the accumulated coverage. 

It is intended that the destination values on the left and the right of the 
above equations be the same framebuffer locations. However, when 
multiple destination buffers are specified (using frontb, backbu, and 
zdraw ) only a single location can be read and used on the right side of 
the equation. By default, the destination RGBA values are read from 
the front buffer in single buffer mode and from the back buffer in double 
buffer mode. If the front buffer is not enabled in single buffer mode, the 
RGBA values are taken from the z-buffer. If the back buffer is not 
enabled in double buffer mode, the RGBA values are taken from the 
front buffer (if possible) or from the z-buffer. 

Blending is available with or without z-buffer mode. When blendfunc- 
tion is set to any value other than (BFONE, BFZERO), logico is forced 
to LOSRC 



c 



c 



c 
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SEE ALSO 

cpack, linesm, logico, pntsmo, polysm 

NOTES 

This subroutine is available only in immediate mode. 

Blending factors BFDA, BFMDA, BFMINS are not supported on 
machines without alpha bitplanes. Blend factor BFMINS is supported 
only on VGX graphics systems. 

This subroutine does not function on IRIS-4D B or G models or on the 
Personal Iris. Use getgde(GDBLEN) to determine whether blending 
hardware is available. 



BUGS 



Blending works properly only in RGB mode. In color map mode, the 
results are unpredictable. 

On some IRIS-4D GT and GTX models, while copying rectangles with 
blending active, readso also specifies the bank from which destination 
color and alpha are read (overriding the blendf setting). 

IRIS-4D VGX models do not clamp color values generated by the spe- 
cial blending function BFMINS,BFONE to 255. Instead, color values 
are allowed to wrap. This will be corrected in the next release. 
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NAME 

blink - changes a color map entry at a selectable rate 

FORTRAN 77 SPECIFICATION 

subroutine blink(rate, i, red, green, blue) 
integer*4 rate, i, red, green, blue 

PARAMETERS 

rate expects the number of vertical retraces per blink. On the stan- 
dard monitor, there are 60 vertical retraces per second. 

i expects an index into the current color map. The color defined at 

that index is the color that is blinked (alternated). 

red expects the red value of the alternate color that blinks against the 
color selected from the color map by the i parameter. 

green expects the green value of the alternate color that blinks against 
the color selected from the color map by the i parameter. 

blue expects the blue value of the alternate color that blinks against 
the color selected from the color map by the i parameter. 



c 



c 



DESCRIPTION 

blink alternates the color located at index i in the current color map with 
the color defined by the parameters red, green, and blue. The rate at 
which the two colors are alternated is set by the rate parameter. The 
maximum number of color map entries that can be blinking simultane- 
ously on a screen is returned by the getgde inquiry GBNBLI. 

The length of time between retraces varies according to the monitor 
used. On the standard monitor, there are 60 retraces per second, so a 
rate of 60 would cause the color to change once every second. 

To terminate blinking and restore the original color for a single color 
map entry, call blink for that entry with rate set to 0. 

To terminate all blinking colors simultaneously, call blink with rate set | 
to -1 . When rate is -1 , the other parameters are ignored. 
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SEE ALSO 

getgde, mapcol 

NOTE 

This routine is available only in immediate mode. 
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NAME 

blkqre - reads multiple entries from the queue 

FORTRAN 77 SPECIFICATION 

integer*4 function blkqre(data, n) {^ 

integer*2 data(*) 
integer*4 n 

PARAMETERS 

data expects the buffer that is to receive the queue information. 
n expects the number of elements in the buffer. 

FUNCTION RETURN VALUE 

The returned value of the function is the number of 16 bit words of data 
actually read into the data buffer. Note that this number will be twice 
the number of complete queue entries read, because each queue entry 
consists of two 16 bit words. ^ 

DESCRIPTION 

blkqre reads multiple entries from the input queue and stores them in 
the array pointed to by data. This function fills the data buffer with 
paired values (a device number and the value of that device). 

SEE ALSO 

qread 

NOTE 

This routine is available only in immediate mode. 



( 
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NAME 



c3f, c3i, c3s, c4f, c4i, c4s - sets the RGB (or RGBA) values for the 
current color vector 

FORTRAN 77 SPECIFICATION 

subroutine c3s(cv) 
integer*2 cv(3) 

subroutine c3i(cv) 
integer*4 cv(3) 

subroutine c3f(cv) 
real cv(3) 

subroutine c4s(cv) 
integer*2 cv(4) 

subroutine c4i(cv) 
integer*4 cv(4) 

subroutine c4f(cv) 
real cv(4) 

The subroutines above are functionally the same but declare their 
parameters differently. 

PARAMETER 

cv For the c4 routines, this parameter expects a four element array con- 
taining RGBA (red, green, blue, and alpha) values. If you use the 
c3 routines, this parameter expects a three element array containing 
RGB values. 

Array components 1, 2, 3, and 4 are red, green, blue, and alpha, 
respectively. Floating point RGBA values range from 0.0 through 
1.0. Integer RGBA values range from through 255. Values that 
exceed the upper limit are clamped to it. Values that exceed the 
lower limit are not clamped, and therefore result in unpredictable 
operation. 
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DESCRIPTION 

c4 sets the red, green, blue, and alpha color components of the currently 
active GL framebuffer, one of normal, popup, overlay, or underlay (see 
drawmo). c3 sets red, green, and blue to the specified values, and sets 
alpha to the maximum value. The current framebuffer must be in RGB 
mode (see RGBmod) for the c command to be applicable. Most draw- 
ing commands copy the current RGBA color components into the color 
bitplanes of the current framebuffer. Color components are retained in 
each draw mode, so when a draw mode is re-entered, red, green, blue, 
and alpha are reset to the last values specified in that draw mode. 

Integer color component values range from 0, specifying no intensity, 
through 255, specifying maximum intensity. Floating point color com- 
ponent values range from 0.0, specifying no intensity, through 1.0, 
specifying maximum intensity. 

It is an error to call c while the current framebuffer is in color map 
mode. 

The color components of all framebuffers in RGB mode are set to zero 
when gconfl is called. 

SEE ALSO 

cpack, drawmo, Imcolo, gRGBco 

NOTE 

These routines can also be used to modify the current material while 
lighting is active (see Imcolo). Note that clamping to 1.0 is disabled in 
this case. 

Because only the normal framebuffer currently supports RGB mode, c 
should be called only while draw mode is NORMAL. Use getgde to 
determine whether RGB mode is available in draw mode NORMAL. 



( 



c 



( 
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NAME 

callob - draws an instance of an object 

FORTRAN 77 SPECIFICATION 

subroutine callob(obj) 
integer*4 obj 

PARAMETERS 

obj expects the object identifier of the object that you want to draw. 

DESCRIPTION 

callob draws an instance of a previously defined object. If callob 
specifies an undefined object, the system ignores the routine. 

Global state attributes are not saved before a call to callob. Thus, if you 
change a variable within an object, such as color, the change can affect 
the caller as well. Use pushat and popatt to preserve global state attri- 
butes across callob calls. 

Likewise, the object may execute transformations that change the matrix 
stack, so you may want to use pushma and popmat to restore the state 
of the matrix stack. 

SEE ALSO 

makeob, popatt, pushat, pushma, popmat 
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NAME 

charst - draws a string of raster characters on the screen 

FORTRAN 77 SPECIFICATION 

subroutine charst(str, length) | 

character*(*) str ^ 

integer*4 length 

PARAMETERS 

str expects the variable containing the string you want to draw. 
length expects the length (number of characters) of the string at str. 

DESCRIPTION 

charst draws a string of text using a raster font. The current character 
position is the position of the first character in the string. After each 
character is drawn, the character's width is added to the current charac- 
ter position. The text string is drawn in the current raster font and color, 
using the current writemask. The system ignores characters that are not f 
defined in the current raster font. v. 

SEE ALSO 

cmov, defras, font, strwid 



c 
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NAME 

chunks - specifies minimum object size in memory 

FORTRAN 77 SPECIFICATION 

subroutine chunks(chunk) 
integer*4 chunk 

PARAMETERS 

chunk Expects the minimum memory size to allocate for an object. As 
you add objects to a display list, chunk is the unit size (in bytes) 
by which the memory allocated to the display list grows. 

DESCRIPTION 

chunks specifies the minimum object memory size. You can call it only 
once after graphics initialization and before the first makeob. 

If you do not use this function, the system assumes a chunk size of 1020 
bytes. This is usually more than large enough. Therefore, you generally 
need to use chunks only if your application is running up against the 
memory limits, and you know that 1020 bytes per object is too much. 

But be careful, if chunks is set too small, complex objects (e.g., multi- 
sided polygons) will not display. Each object in a display list must fit 
entirely into a single chunk. Some experimentation may be necessary to 
determine the optimal chunksize for an application. 

SEE ALSO 

compac, makeob 

NOTE 

This routine is available only in immediate mode. 
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NAME 

circ, circi, circs - outlines a circle 

FORTRAN 77 SPECIFICATION 

subroutine circ(x, y, radius) I 

real x, y, radius 

subroutine circi(x, y, radius) 
integer*4 x, y, radius 

subroutine circs(x, y, radius) 
integer*2 x, y, radius 

The routines above are functionally the same. However, the type 
declarations for the coordinates differ. 

PARAMETERS 



x expects the x coordinate of the center of the circle specified in 

world coordinates. 

y expects the y coordinate of the center of the circle specified in 

world coordinates. 

radius expects the length of the radius of the circle. 

DESCRIPTION 

circ draws an unfilled circle in the x-y plane with z assumed to be zero. 
To create a circle that does not lie in the x-y plane, draw the circle in the 
x-y plane, then rotate and/or translate the circle. Note that circles rotated 
outside the 2-D x-y plane appear as ellipses. 

A circle is drawn as a sequence of line segments, and therefore inherits 
all properties that affect the drawing of lines. These include the current 
color, writemask, line width, stipple pattern, shade model, line antialias- 
ing mode, and subpixel mode. The stipple pattern is initialized to bit 
zero of the current linestyle before the circle is drawn, then shifted con- 
tinuously through the segments of the circle. 



c 



c 



Version 3.0 -1- April 1990 



circ Graphics Reference, FORTRAN circ 



After circ executes, the graphics position is undefined. 

SEE ALSO 

arc, bgnclo, circf, crvn, linewi, linesm, Isrepe, scrsub, setlin, shadem, 
subpix 



BUGS 



When the line width is greater than 1, small notches will appear in cir- 
cles, because of the way wide lines are implemented. 
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NAME 

circf, circfi, circfs - draws a filled circle 

FORTRAN 77 SPECIFICATION 

subroutine circf(x, y, radius) I 

real x, y, radius 

subroutine circfi(x, y, radius) 
integer*4 x, y, radius 

subroutine circfs(x, y, radius) 
integer*2 x, y, radius 

The routines above are functionally the same even though the type 
declarations for the coordinates differ. 

PARAMETERS 



x expects the x coordinate of the center of the filled circle 

specified in world coordinates. 

y expects the y coordinate of the center of the filled circle 

specified in world coordinates. 

radius expects the length of the radius of the filled circle. 

DESCRIPTION 

circf draws a filled circle in the x-y plane (z = 0). To draw a circle in. a 
plane other than the x-y plane, define the circle in the x-y plane and then 
rotate or translate the circle. Note that filled circles rotated outside the 
2-D x-y plane appear as filled ellipses. 

A circle is drawn as a single polygon, and therefore inherits all proper- 
ties that affect the drawing of polygons. These include the current color, 
writemask, fill pattern, shade model, polygon antialiasing mode, 
polygon scan conversion mode, and subpixel mode. Front-face and 
back-face elimination work correctly with filled circles, which are 
front-facing when viewed from the positive z half-space. 



( 



c 
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After circf executes, the graphics position is undefined. 

SEE ALSO 

arcf, backfa, bgnpol, circ, frontf, polymo, polysm, scrsub, setpat, 
shadem, subpix 
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NAME 

clear - clears the viewport 

FORTRAN 77 SPECIFICATION 
subroutine clear 

PARAMETERS 

none 

DESCRIPTION 

clear sets the bitplane area of the viewport to the current color. Multi- 
ple bitplane buffers can be cleared simultaneously using the backbu, 
frontb, and zdraw commands. Current polygon fill pattern and wri- 
temask affect the operation of clear. The screen mask, when it is set to 
a subregion of the viewport, bounds the cleared region. Alpha function, 
blend function, logical operation, stenciling, texture mapping, and z 
buffering, however, are ignored by clear. Stencil and z buffer contents 
are not affected by clear (except in the special case of zdraw). 

Like other drawing commands, clear operates on the currently active 
framebuffer, one of normal, popup, overlay, or underlay, based on the 
current draw mode (see drawmo). 

After clear executes, the graphics position is undefined. 

SEE ALSO 

afunct, backbu, blendf, czclea, drawmo, frontb, logico, scrmas, setpat, 
stenci, texbin, zbuffe, zdraw 

NOTE 

On the IRIS-4D B, G, GT, GTX, and VGX models, clear runs faster 
when the window is completely unobscured. 

On the Personal Iris, clear runs faster when the visible window area 
consists of four or fewer rectangular regions. 



c 



c 
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NAME 

clearh - sets the hitcode to zero 

FORTRAN 77 SPECIFICATION 
subroutine clearh 

PARAMETERS 

none 

DESCRIPTION 

clearh clears the global variable hitcode, which records clipping plane 
hits in picking and selecting modes. 

SEE ALSO 

gethitcode, gselect, pick 

NOTES 

This routine is available only in immediate mode. 

This routine only functions on IRIS-4D B and G models, and therefore 
we advise against its use in new development. 
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NAME 

clippl - specify a plane against which all geometry is clipped 

FORTRAN SPECIFICATION 

subroutine clippl(index 3 mode, params) 
integer*4 index, mode 
real paramsQ 

PARAMETERS 

index expects an integer in the range through 5, indicating which of 
the 6 clipping planes is being modified. 

mode expects one of three tokens: 

CPDEFI: use the plane equation passed in params to define a 
clipplane. The clipplane is neither enabled nor disabled. 

CPON: enable the (previously defined) clipplane. 

CPOFF: disable the clipplane. (default) 

params expects an array of 4 floats that specify a plane equation. A 
plane equation is usually thought of as a 4-vector [A,B,C,D]. 
In this case, A is the first component of the params array, and 
D is the last. A 4-component vertex array (see v4f) can be 
passed as a plane equation, where vertex X becomes A, Y 
becomes B, etc. 

DESCRIPTION 

Geometry is always clipped against the boundaries of a 6-plane frustum 
in x, y, and z. clippl allows the specification of additional planes, not 
necessarily perpendicular to the x, y, or z axes, against which all 
geometry is clipped. Up to 6 additional planes can be specified. 
Because the resulting clipping region is always the intersection of the 
(up to) 12 half -spaces, it is always convex. 

clippl specifies a half-space using a 4-component plane equation. When g 
it is called with mode CPDEFI, this object-coordinate plane equation is I 
transformed to eye-coordinates using the inverse of the current Model- 
View matrix. 
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A defined clipplane is then enabled by calling clippl with the CPON 
argument, and with arbitrary values passed in params. While drawing 
after a clipplane has been defined and enabled, each vertex is 
transformed to eye-coordinates, where it is dotted with the transformed 
clipping plane equation. Eye-coordinate vertexes whose dot product 
with the transformed clipping plane equation is positive or zero are in, 
and require no clipping. Those eye-coordinate vertexes whose dot pro- 
duct is negative are clipped. Because clippl clipping is done in eye- 
coordinates, changes to the projection matrix have no effect on its 
operation. 

By default all six clipping planes are undefined and disabled. The 
behavior of an enabled but undefined clipplane is undefined. 

NOTES 

IRIS-4D models G, GT, and GTX, and the Personal Iris, do not imple- 
ment clippl. Use getgde to determine whether user-defined clipping 
planes are supported. 

clippl cannot be used while mmode is MSINGL. 

A point and a normal are converted to a plane equation in the following 
manner: 

point = [Px,Py,Pz] 

normal = |Nx| 
|Ny| 
|Nz| 

plane equation = |A| 
|B| 
|C| 
ID | 

A = Nx 
B = Ny 
C = Nz 
D = -[Px,Py,Pz] dot |Nx| 

|Ny| 

|Nz| 
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NAME 

clkon, clkoff - control keyboard click 

FORTRAN 77 SPECIFICATION 
subroutine clkon 
subroutine clkoff 

PARAMETERS 

none 

DESCRIPTION 

clkon and clkoff control the keyboard click. 

SEE ALSO 

lampon, ringbe, setbel 

NOTE 

This routine is available only in immediate mode. 



c 



c 
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NAME 

closeo - closes an object definition 

FORTRAN 77 SPECIFICATION 
subroutine closeo 

PARAMETERS 

none 

DESCRIPTION 

closeo closes an open object definition. Use makeob to open a 
definition for a new object. All display list routines between makeob 
and closeo become part of the object definition. Use editob to open an 
existing object fojrie_dit^ 

If no object is open, closeo is ignored. 

SEE ALSO 

editob, makeob 

NOTE 

This routine is available only in immediate mode. 
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NAME 

cmode - sets color map mode as the current mode. 

FORTRAN 77 SPECIFICATION 
subroutine cmode 

PARAMETERS 

none 

DESCRIPTION 

cmode instructs the system to treat color as a 1 -component entity in the 
currently active drawmode. The single color component is used as an 
index into a table of RGB color values called the color map. Because 
color map mode is the default value for all GL framebuffers, it can be 
called in any of the framebuffer drawmodes (NORMAL, PUPDRA, 
OVERDR, and UNDERD). To return the normal framebuffer to color 
map mode, however, you must call cmode while in drawmode NOR- 
MAL. You must call gconfi for cmode to take effect. 

While in color map mode, a framebuffer is configured to store a single 
color index at each pixel location. The framebuffer is displayed by con- 
tinually translating color indices into RGB triples using the 
framebuffer's color map, a table of index-to-RGB mappings. The red, 
green, and blue components stored in the color map are used (after 
correction for monitor non-linearity) to directly control the color guns of 
the monitor. Colors and writemasks must be specified using color map- 
compatible commands such as color, colorf, and writem. 

Many advanced rendering features, such as texture mapping, polygon 
antialiasing, and fog, are available only in RGB mode. Color map mode 
lighting, while functional, is substantially less robust than its RGB mode 
counterpart. 

Since cmode is the default, you do not have to call it unless the normal 
framebuffer was previously set to RGB mode. 



c 



c 



( 
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SEE ALSO 

color, drawmo, gconfi, getdis, getgde, multim, onemap, RGBmod, wri- 
tem 

NOTE 

Color map mode is available in all framebuffers of all hardware 
configurations, getgde can be used to determine how many bitplanes in 
each of the normal, popup, overlay, and underlay framebuffers are avail- 
able in both single and double buffered color map mode. 

This routine is available only in immediate mode. 
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NAME 

cmov, cmovi, cmovs, cmov2, cmov2i, cmov2s - updates the current 
character position 

FORTRAN 77 SPECIFICATION f 

subroutine cmov(x, y, z) ^ 

real x, y, z 

subroutine cmovi(x, y, z) 
integer*4 x, y, z 

subroutine cmovs(x, y, z) 
integer*2 x, y, z 

subroutine cmov2(x, y) 
real x, y 

subroutine cmov2i(x, y) 
integer*4 x, y 

subroutine cmov2s(x, y) 
integer*2 x, y 

All of the above functions are functionally the same except for the type I 
declarations of the parameters. In addition the cmov2* routines assume 
a 2-D point instead of a 3-D point. 

PARAMETERS 

x expects the x location of the point (in world coordinates) to which 
you want to move the current character position. 

y expects the y location of the point (in world coordinates) to which 
you want to move the current character position. 

z expects the z location of the point (in world coordinates) to which 
you want to move the current character position. (This parameter not 
used by the 2-D subroutines.) 



DESCRIPTION 

cmov moves the current character position to a specified point (just as 
move sets the current graphics position), cmov transforms the specified 
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world coordinates into screen coordinates, which become the new char- 
acter position. If the transformed point is outside the viewport, the char- 
acter position is undefined. 

cmov does not affect the current graphics position. 

SEE ALSO 

charst, move, readpi, readRG, writep, writeR 
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NAME 

color, colorf - sets the color index in the current draw mode 

FORTRAN 77 SPECIFICATION 

subroutine color(c) 
integer*4 c 

subroutine colorf(c) 
real c 

PARAMETERS 

c expects an index into the current color map. 

DESCRIPTION 

color sets the color index of the currently active GL framebuffer, one of 
normal, popup, overlay, or underlay (see drawmo). The current frame- 
buffer must be in color map mode (see cmode) for the color command 
to be applicable. Most drawing commands copy the current color index 
into the color bitplanes of the current framebuffer. color is retained in 
each draw mode, so when a draw mode is re-entered, color is reset to the 
last value specified in that draw mode. 

color values range from through 2 n -l, where n is the number of bit- 
planes available in the current draw mode, n can be ascertained by cal- 
ling getpla while in the desired draw mode, or by calling getgde at any 
time. Color indices larger than 2 n -l are clamped to 2 n -l; color indices 
less than zero yield undefined results. 

The color displayed by a given color index is determined by the current 
color map (see mapcol.) Each draw mode has its own color map. 

colorf is identical to color, except that it expects a floating point color 
index. Before the color is written into display memory, it is rounded to 
the nearest integer value. When drawing with the GOURAU shading 
model, machines that iterate color indices with fractional precision yield 
more precise shading results using colorf than with color. The results 
of color and colorf are indistinguishable when drawing with FLAT 
shading. 
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It is an error to call color or colorf while the current framebuffer is in 
RGB mode. 

The color indices of all framebuffers in color map mode are set to zero 
when gconfi is called. 

SEE ALSO 

drawmo, getcol, mapcol, writem 



NOTE 



IRIS-4D B, G, GT, and GTX models do not iterate color with fractional 
precision, nor do early serial numbers of the Personal Iris. Use 
getgde(GDCIFR) to determine whether fractional color index iteration 
is supported. 
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NAME 

compac - compacts the memory storage of an object 

FORTRAN 77 SPECIFICATION 

subroutine compac(obj) I 

integer*4obj 

PARAMETERS 

ohj expects the object identifier for the object you want to compact. 

DESCRIPTION 

When you modify an open object definition (using the object editing 
routines), the memory storage for the object definition can become frag- 
mented. A call to compac can make a fragmented object definition 
occupy a continuous section of memory. 

Although you can call compac to explicitly compact an object, it is 
rarely necessary because a call to closeo automatically calls compac, 
when the object definition becomes too fragmented. (After you edit an / 
object, you must always call closeo.) ^ 

Because compac, requires a significant amount of time, do not call it 
unless storage space is critical and you cannot tolerate even the small 
amount of fragmentation allowed by closeo. 

SEE ALSO 

closeo, chunks 

NOTE 

This routine is available only in immediate mode. 



( 
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NAME 

concav - allows the system to draw concave polygons 

FORTRAN 77 SPECIFICATION 

subroutine concav(b) 
logical b 

PARAMETERS 

h expects either .TRUE, or .FALSE.. 

.TRUE, tells the system to expect concave polygons. 

.FALSE, tells the system to expect no concave polygons. This is the 
default. 

DESCRIPTION 

concav tells the system whether or not to expect concave polygons. If 
you try to draw a concave polygon while the system does not expect it, 
the results are unpredictable. Although calling concav(.TRUE.) 
guarantees that all non-selfintersecting polygons will be drawn correctly, 
the performance of non-concave polygons is reduced on some machines. 
Polygons whose edges intersect each other are never guaranteed to be 
drawn correctly. 

In all cases, performance is optimized when concave polygons are 
decomposed into convex pieces before being passed to a GL drawing 
routine. 

SEE ALSO 

bgnpol 



BUG 



IRIS-4D GT and GTX models always expect concave polygons, regard- 
less of the value of the concav flag. 
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NAME 

cpack - specifies RGB A color with a single packed 32-bit integer 

FORTRAN 77 SPECIFICATION 

subroutine cpack(pack) I 

integer*4 pack 

PARAMETERS 

pack expects a packed integer containing the RGBA (red, green, blue, 
alpha) values you want to assign as the current color. Expressed 
in hexadecimal, the format of the packed integer is $aabbggrr, 
where: 

aa is the alpha value, 

bb is the blue value, 

gg is the green value, and 

rr is the red value. 

RGBA component values range from to $FF (255). 

DESCRIPTION 

cpack sets the red, green, blue, and alpha color components of the 
currently active GL framebuffer, one of normal, popup, overlay, or 
underlay (see drawmo). The current framebuffer must be in RGB mode 
(see RGBmod) for the cpack command to be applicable. Most drawing 
commands copy the current RGBA color components into the color bit- 
planes of the current framebuffer. Color components are retained in 
each draw mode, so when a draw mode is re-entered, red, green, blue, 
and alpha are reset to the last value specified in that draw mode. 

Color component values range from 0, specifying no intensity, through 
255, specifying maximum intensity. For example, cpack($FF004080) 
sets red to 16#80# (half intensity), green to 16#40# (quarter intensity), 
blue to (off), and alpha to 16#FF# (full intensity). 

It is an error to call cpack while the current framebuffer is in color map 
mode. 



( 



c 
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The color components of all framebuffers in RGB mode are set to zero 
when gconfl is called. 

SEE ALSO 

c, drawmo, gRGBco, Imcolo 

NOTE 

cpack can also be used to modify the current material while lighting is 
active (see Imcolo). 

Because only the normal framebuffer currently supports RGB mode, 
cpack should be called only while draw mode is NORMAL. Use 
getgde to determine whether RGB mode is available in draw mode 
NORMAL. 
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NAME 

crv - draws a curve 

FORTRAN 77 SPECIFICATION 

subroutine crv(points) | 

real points(3,4) ^ 

PARAMETERS 

points expects an array containing the four points that define the 
curve. The routine expects 3-D points (x, y, and z coordinates 
for each point). 

DESCRIPTION 

crv draws a cubic spline curve segment (defined by the four submitted 
points) according to the current curve basis and precision. 

The curve segment is approximated by a sequence of straight lines. All 
lines use the current linestyle, which is reset prior to the first line and 
continues through subsequent lines. Other line modes, including depth- 
cueing, line width, and line antialiasing, also apply to the lines gen- 
erated by crv. 

After crv executes, the graphics position is undefined. 

SEE ALSO 

crvn, curveb, curvep, defbas, depthc, linesm, linewd, rcrv, rcrvn, setlin 



( 



c 



Version 3.0 ■ ' -1- April 1990 



crvn Graphics Reference, FORTRAN crvn 

NAME 

crvn - draws a series of curve segments 

FORTRAN 77 SPECIFICATION 

subroutine crvn(n, geom) 
integer*4 n 
real geom(3,n) 

PARAMETERS 

geom expects a matrix of 3-D points. 

n expects the number of points in the matrix referenced by geom. 

DESCRIPTION 

crvn draws a series of cubic spline segments using the current basis and 
precision. The control points determine the shapes of the curve seg- 
ments and are used sequentially four at a time. 

For example, if there are six control points, there are three possible 
sequential selections of four control points. Thus, crvn draws three 
curve segments: the first using control points 0,1,2,3; the second using 
control points 1,2,3,4; and the third using control points 2,3,4,5. 

If the current basis is a B-spline, a Cardinal spline, or a basis with simi- 
lar properties, the curve segments are joined end to end and appear as a 
single curve. 

Each curve segment is approximated by a sequence of straight lines. All 
lines use the current linestyle, which is reset prior to the first line and 
continues through subsequent lines. Other line modes, including depth- 
cueing, line width, and line antialiasing, also apply to the lines gen- 
erated by crvn. 

After crvn executes, the graphics position is undefined. 

SEE ALSO 

crv, curveb, curvep, defbas, depthc, linesm, linewd, rcrv, rcrvn, setlin 
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NAME 

curori - sets the origin of a cursor 

FORTRAN 77 SPECIFICATION 

subroutine curori(n ? xorign, yorign) | 

integer*4 n, xorign, yorign ^ 

PARAMETERS 

n expects an index into the cursor table created by defcur. 

xorign expects the x distance of the origin relative to the lower left 
corner of the cursor. 

yorign expects the y distance of the origin relative to the lower left 
corner of the cursor. 



DESCRIPTION 

curori sets the origin of a cursor. The origin is the point on the cursor 
that aligns with the current cursor valuators. The lower left corner of 
the cursor has coordinates (0,0). Before calling curori, the cursor must I 
be defined with defcur. curori does not take effect until you call 
setcur. 

The default origin for curori is at (0,0) for user-defined glyphs. 

SEE ALSO 

attach, defcur, setcur 

NOTE 

This routine is available only in immediate mode. 



c 
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NAME 

curson, cursof - control cursor visibility by window 

FORTRAN 77 SPECIFICATION 
subroutine curson 
subroutine cursof 

PARAMETERS 

none 

DESCRIPTION 

curson and cursof control the visibility of the cursor in the current win- 
dow. The default is curson. 

Use getcur to find out if the cursor is visible. 

SEE ALSO 

getcur 

NOTE 

This routine is available only in immediate mode. 



BUG 



On the Personal IRIS, cursor visibility is a global resource. The calls 
curson and cursof control cursor visibility regardless of its position on 
the screen. If a process turns off the cursor, it will remain off until that 
process is killed or the cursor is turned back on by a call to curson. 
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NAME 

cursty - defines the type and/or size of cursor 

FORTRAN 77 SPECIFICATION 

subroutine cursty(typ) 
integer*4 typ 

PARAMETERS 

type expects one of five values that describe the cursor: 

C16X1: the default, a 16x16 bitmap cursor of no more than one 
color. 

C16X2: a 16x16 bitmap cursor of no more than three colors. 

C32X1: a 32x32 bitmap cursor of no more than one color. 

C32X2: a 32x32 bitmap cursor of no more than three colors. 

CCROSS: a cross-hair cursor. 

DESCRIPTION 

cursty defines the type and size of a cursor. After you call cursty call 
defcur to specify the glyph's bitmap and to assign a numeric name to it. 

The cross-hair cursor is formed with a horizontal line and a vertical line 
(each 1 pixel wide) that extend completely across the screen. Its origin 
(15,15) is at the intersection of the two lines. It is a single-color cursor 
whose color is mapped by the color index returned by the getgde 
inquiry GDXHCI. 

SEE ALSO 

defcur, curori, getgde 

NOTES 

This routine is available only in immediate mode. 



c 
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Cursor types C16X2 and C32X2 are not available on systems where the 
getgde inquiry GDBCUR returns 1. 
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NAME 

curveb - selects a basis matrix used to draw curves 

FORTRAN 77 SPECIFICATION 

subroutine curveb(basid) 
integer*4 basid 

PARAMETERS 

basid expects the basis identifier of the basis matrix you want to use 
when drawing a curve. (You must have previously called defbas 
to assign a basis identifier to a basis matrix.) 

DESCRIPTION 

curveb selects a basis matrix (by its basis identifier) as the current basis 
matrix to draw curve segments. The basis matrix determines how the 
system uses the control points when drawing a curve. Depending on the 
basis matrix, the system draws bezier curves, cardinal spline curves, b- 
spline curves and others. The system does not restrict you to a limited 
set of basis matrices. You can define basis matrices to match whatever 
constraints you want to place on the curve. 

SEE ALSO 

crv, crvn, curvep, defbas 



c 
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NAME 

curvei - draws a curve segment 

FORTRAN 77 SPECIFICATION 

subroutine curvei(count) 
integer*4 count 

PARAMETERS 



DESCRIPTION 

curveit iterates the matrix on top of the matrix stack as a forward differ- 
ence matrix count times, curveit issues a draw routine with each itera- 
tion, curveit accesses low-level hardware capabilities for curve draw- 
ing. 

SEE ALSO 

crv 
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NAME 

curvep - sets number of line segments used to draw a curve segment 

FORTRAN 77 SPECIFICATION 

subroutine curvep(nsegs) ■ 

integer*4 nsegs 

PARAMETERS 

nsegs expects the number of line segments to use when drawing a 
curve segment. 

DESCRIPTION 

curvep sets the number of line segments used to draw a curve. When- 
ever crv, crvn, rcrv, or rcrvn execute, a number of straight line seg- 
ments approximate each curve segment. The greater the value of nsegs, 
the smoother the curve appears, but the longer the drawing time. 

SEE ALSO f 

crv, crvn, curveb, rcrv, rcrvn ^ 



( 
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NAME 

cyclem - cycles between color maps at a specified rate 

FORTRAN 77 SPECIFICATION 

subroutine cyclem(durati, map, nxtmap) 
integer*4 durati, map, nxtmap 

PARAMETERS 

durati expects the number of vertical traces before switching to the 
map named by nxtmap. 

map expects the number of the map to use before completing the 
number of vertical sweeps specified by durati. 

nxtmap expects the number of the map to use after completing the 
number of vertical sweeps specified by durati. 

DESCRIPTION 

When the system is in multimap mode, cyclem allows you to switch 
from one color map to another after a specified duration. In multimap 
mode there are 16 color maps, numbered 0-15. You can use cyclem 
within a loop if you want to cycle through more than one map. 

EXAMPLE 

The code fragment sets up multimap mode and cycle between two maps, 
leaving map 1 on for ten vertical retraces and map 3 on for five retraces. 

call multim 

call gconfi 

call cyclem(10, 1, 3) 

call cyclem(5, 3, 1) 

SEE ALSO 

blink, gconfi, multim 
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NOTE 

This routine is available only in immediate mode and cannot be used in 
onemap mode. 



( 



( 



( 
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NAME 

czclea - clears the color bitplanes and the z-buffer simultaneously 

FORTRAN 77 SPECIFICATION 

subroutine czclea(cval, zval) 
integer*4 cval, zval 

PARAMETERS 

cval expects the color to which you want to clear the color bitplanes. 
zval expects the depth value to which you want to clear the z-buffer. 

DESCRIPTION 

czlear sets the color bitplanes in the area of the viewport to cval, and the 
z buffer bitplanes in the area of the viewport to zval Multiple color bit- 
plane buffers can be cleared simultaneously using the backbu and 
frontb commands. The screen mask, when it is set to a subregion of the 
viewport, bounds the cleared region. Most other drawing modes, 
including alpha function, blend function, logical operation, polygon fill 
pattern, stenciling, texture mapping, writemask, and z buffering, have no 
effect on the operation of czclea. The current color does not change. 

Because only the normal framebuffer includes a z buffer, czclea should 
be called only while draw mode is NORMAL. 

In RGB mode, the cval parameter expects a packed integer of the same 
format used by cpack, namely $aaggbbrr, where rr is the red value, bb 
the blue value, gg the green value, and aa is the alpha value. In color 
map mode this parameter expects an index into the current color map, so 
only up to 12 of the least-significant bits are significant. 

The valid range of the zval parameter depends on the graphics hardware, 
where the minimum is the value returned by getgde(GDZMIN) and the 
maximum is the value returned by getgde(GDZMAX). It is unaffected 
by the state of the GLCZRA compatibility mode (see glcomp). 

After czclea executes, the graphics position is undefined. 
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SEE ALSO 

afunct, blendf, clear, cpack, getgde, glcomp, logico, scrmas, setpat, 
stenci, texbin, wmpack, writem, zbuffe, zclear, zfunct 

NOTES 

Whenever you need to clear both the z-buffer and the color bitplanes to 
constant values at the same time, use czclea. A simultaneous clear will 
take place if circumstances allow it. There is never a penalty in calling 
czclea over calling clear and zclear sequentially. 

IRIS-4D GT and GTX models can do a simultaneous clear only under 
the following circumstances: 

• In RGB mode, the 24 least significant bits of cval (red, green, and 
blue) must be identical to the 24 least significant bits of zvah 

• In color map mode, the 12 least significant bits of cval must be 
identical to the 12 least significant bits of zval. 

IRIS-4D VGX models always clear color and z bitplanes banks sequen- 
tially, regardless of the values of cval and zval 

On the Personal Iris, you can speed up czclea by as much as a factor of 
four for common values of zval if you call zfunct in conjunction with it 
such that one of the following conditions are met: 



zval 



zfunct 



getgde(GDZMIN) 
getgde(GDZMAX) 



ZF GREATER or ZF GEQUAL 
ZF LESS or ZF LEQUAL 



c 



c 



BUGS 

IRIS-4D G models always clear their z-buffers to GDZMAX, regardless 
of the value passed to czclea. 



( 
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NAME 

dbtext - sets the dial and button box text display 

FORTRAN 77 SPECIFICATION 

subroutine dbtext(str) 
character*(8) str 

PARAMETERS 

str expects a variable containing a text string of no more than eight 
characters: digits, spaces, and uppercase letters only. 

DESCRIPTION 

dbtext places up to eight characters of text into the text display on the 
dial and button box. 

SEE ALSO 

setdbl 

NOTES 

This routine is available only in immediate mode. 

As might be expected, this routine does not function if you use the dial 
and button box without a text display. 
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NAME 

defbas - defines a basis matrix 

FORTRAN 77 SPECIFICATION 

subroutine defbas(id, mat) ■ 

integer*4id 

real mat(4,4) 

PARAMETERS 

id expects the basis matrix identifier you want to assign to the matrix 
at mat 

mat expects the matrix to which you want to assign the basis matrix 
identifier, id. 

DESCRIPTION 

defbas assigns a basis matrix identifier to a basis matrix. The basis 
matrix is used by the routines that generate curves and patches. Use the 
basis matrix identifier in subsequent calls to curveb and patchb. f 

SEE ALSO 

crv, crvn, curveb, curvep, patch, patchb, patchp, patchc, rcrv, rcrvn 

NOTE 

This routine is available only in immediate mode. 



( 
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NAME 

defcur - defines a cursor glyph 

FORTRAN 77 SPECIFICATION 

subroutine defcur(n, curs) 
integer*4 n 
integer*2 curs(*) 

PARAMETERS 

n expects the constant you want to assign as a cursor name. By 
default, an arrow is defined as cursor and cannot be redefined. 

curs expects the bitmap for the cursor you want to define. The bitmap 
can be 16x16 or 32x32 and either one or two layers deep. This 
parameter is ignored for cross-hair cursors. 

DESCRIPTION 

defcur defines a cursor glyph with the specified name and bitmap. Call 
cursty prior to calling defcur to set the type and size of cursor it 
defines. The name parameter n is used to identify the cursor glyph to 
other cursor routines. A subsequent call to defcur with the same value 
of n will replace the current definition of the cursor with the new one. 

By default, the cursor origin of a bitmap cursor is at (0,0), its lower-left 
corner, and the cursor origin of a cross-hair cursor is at (15,15), the 
intersection of its two lines. Use curori to set the cursor origin to some- 
where else. The cursor origin is the position controlled by valuators 
attached to the cursor, and is also the position pick uses for the picking 
region. 

SEE ALSO 

curori, cursty, getcur, getgde, pick, setcur 

NOTES 

This routine is available only in immediate mode. 
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Some models do not support two-layer cursor bitmaps. Use the getgde 
inquiry GDBCUR to determine how many layers are supported. 



c 



c 



( 
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NAME 

deflin - defines a linestyle 

FORTRAN 77 SPECIFICATION 

subroutine deflin(n, Is) 
integer*4 n, Is 

PARAMETERS 

n expects the constant that you want to use as an identifier for the 
linestyle described by Is. This constant is used as an index into a 
table of linestyles. By default, index contains the pattern $FFFF, 
which draws solid lines and cannot be redefined. 



Is expects a 16-bit pattern to use as a linestyle. This pattern is stored in 
the linest 
linestyles, 



the linestyle table at index n. You can define up to 2 16 distinct 



DESCRIPTION 

deflin defines a linestyle which is a write-enabled pattern that is applied 
when lines are drawn. The least-significant bit of the linestyle is applied 
first. To replace a linestyle, respecify the previous index. 

SEE ALSO 

defcur, deipat, defras, getlst, Isrepe, setlin 

NOTES 

This routine is available only in immediate mode. 

On the Personal Iris, there is a performance penalty for drawing non- 
solid lines; there is no penalty on the other IRIS-4D models. 
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NAME 

defpat - defines patterns 

FORTRAN 77 SPECIFICATION 

subroutine defpat(n, size, mask) 

integer*4 n, size 

integer*2 mask((size*size)/16) 

PARAMETERS 

n expects the constant that you want to use as an identifier for the 
pattern described by mask. This constant is used as an index into 
a table of patterns. By default, pattern is a 16X16 solid pattern 
that cannot be changed. 

size expects the size of the pattern: 16, 32, or 64 for a 16x16-, 
32x32-, or 64x64-bit pattern, respectively. 

mash expects an array of 16-bit integers that form the actual bit pat- 
tern. The system stores the pattern in a pattern table at index n. 
The pattern is described from left to right and bottom to top, just 
as characters are described in a raster font. 

DESCRIPTION 

defpat allows you to define an arbitrary pattern and assign it an 
identifier. You can later reference this pattern in other routines via its 
identifier. Patterns are available to all windows when using multiple 
windows. 

Patterns affect the filling of polygons, including rectangles, arcs, and cir- 
cles, as well as polygons specified with individual vertices. Patterns 
have no effect on the scan conversion of points, lines, or characters, or 
on pixel write or copy operations. 

When a pattern is active (see setpat) it is effectively replicated across 
the entire screen, with the edges of pattern tiles aligned to the left and 
bottom edges of the screen. Bit 15 of each 16-bit description word is 
leftmost, and words are assembled left to right, then bottom to top, to 
form each pattern square. Pixels on the screen that correspond to zeros 
in the pattern remain unmodified during scan conversion of polygons. 
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No changes are made to any bitplane bank of a protected pixel. 

SEE ALSO 

deflin, defras, getpat, setpat 

NOTES 

This routine is available only in immediate mode. 

Some machines do not support 64x64 patterns. Call getgde(GDPATS) 
to determine the availability of 64x64 patterns. 

On the Personal Iris there is a performance penalty for non-solid pat- 
terns. 
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NAME 

defras - defines a raster font 

FORTRAN 77 SPECIFICATION 

subroutine defras(n, ht, nc, chars, nr, raster) I 

integer*4 n, ht, nc, nr 
integer*! chars(4*nc), raster(nr) 

PARAMETERS 

n expects the constant that you want to use as the identifier for this 
raster font. This constant is used as an index into a font table. 
The default font, 0, is a fixed-pitch font with a height of 16 and 
width of 9. Font cannot be redefined. 

ht expects the maximum height (in pixels) for a character. 

nc expects the number of characters in this font. 

chars expects an array of four by nc 16-bit elements. Because you will 

need to write to individual bytes within the second and third ele- ^ 
ments of the chars array, you should declare an eight by nc array I 
of one byte elements. You can then EQUIVALENCE the new 
array to the the chars array. 

First element of each row expects the element number of raster 
at which starts the bitmap for this character. The element 
numbers start at zero. 

Second element, high byte expects the number of columns in 
the bitmap that contain set bits (character width). Second ele- 
ment, low byte expects the number of rows (character height) in 
the bitmap of the character (including ascender and descender). 

Third element, high byte expects number of bitmap columns 
between the start of the character's bitmap and the start of the 
character. Third element, low byte expects the number rows 
between the character's baseline and the bottom of the bitmap. 
For characters with descenders (e.g., g) this value is a negative ■ 
number. For characters that rest entirely on the baseline, this ^ 
value is zero. 
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Fourth element expects the bit width of the bitmap for the char- 
acter. This value tells the system how many bits there are in each 
row of the bitmap for this character. 

nr expects the number of 1 6-bit integers in raster. 

raster expects a one-dimensional array that contains all the bit maps 
(masks) for the characters in the font. Each element of the array 
is a 16-bit integer and the elements are ordered left to right, bot- 
tom to top. When interpreting each element, the bits are left 
justified within the character's bounding box. 

The maximum row width for a single bitmap is not limited to the 
capacity of a single 16-bit integer array element. The rows of a 
bitmap may span more than one array element. However, each 
new row in the character bitmap must start with its own array 
element. Likewise, each new character bitmap must start with 
its own array element. The system reads the row width and start- 
ing location for a character bitmap from the in the chars array. 

DESCRIPTION 

defras defines a raster font. The hardest part of creating a new raster 
font is generating a bit map for each character. You may want to write a 
graphically oriented tool for creating the bitmaps expected by raster. 

To replace a raster font, specify the index of the previous font as the 
index for the new font. To delete a raster font, define a font with no 
characters. Patterns, cursors, and fonts are available to all windows 
when using multiple windows. 

SEE ALSO 

charst, cmove, font, getcpo, getdes, getfon, gethei, strwid 

NOTE 

This routine is available only in immediate mode. 
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NAME 

delobj - deletes an object 

FORTRAN 77 SPECIFICATION 

subroutine delobj(obj) I 

integer*4 obj 

PARAMETERS 

obj expects the object identifier of the object that you want to delete. 

DESCRIPTION 

delobj deletes an object. Deleting an object frees most of its display list 
storage; the object identifier remains undefined until you create a new 
object for that identifier. The system ignores calls to delete objects that 
don't exist. 

SEE ALSO 

compac, makeob C 

NOTE 

This routine is available only in immediate mode. 



( 
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NAME 

deltag - deletes a tag from the current open object 

FORTRAN 77 SPECIFICATION 

subroutine deltag(t) 
integer*4 1 

PARAMETERS 

t expects the tag that you want to delete. 

DESCRIPTION 

deltag deletes the specified tag from the object currently open for edit- 
ing. You cannot delete the special tags STARTT and ENDTAG. 

SEE ALSO 

editob, maketa 

NOTE 

This routine is available only in immediate mode. 
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NAME 

depthc - turns depth-cue mode on and off 

FORTRAN 77 SPECIFICATION 

subroutine depthc(mode) | 

logical mode ^ 

PARAMETERS 

mode expects either .TRUE, or .FALSE.. 
.TRUE, turns depthcue mode on. 
.FALSE, turns depthcue mode off. 

DESCRIPTION 

depthc turns depth-cue mode on or off. If depth-cue mode is on, all 
lines, points, characters, and polygons are drawn depth-cued. This 
means the z values and the range of color values specified by Ishade or 
IRGBra determine the color of the lines, points, characters, or polygons. 
The z values, whose range is set by Isetde, are mapped linearly into the I 
range of color values. In this mode, lines that vary greatly in z value ^ 
span the range of colors specified by Ishade or IRGBra. 

In color index mode, the color map entries specified by Ishader should 
be loaded with a series of colors that gradually increase or decrease in 
intensity. 

SEE ALSO 

IRGBra, Isetde, Ishade 



( 
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NAME 

dglclo - closes the DGL server connection 

FORTRAN 77 SPECIFICATION 

subroutine dglclo(sid) 
integer*4 sid 

PARAMETERS 

sid expects the identifier of the server you want to close. If sid is nega- 
tive, then all graphics server connections are closed. Server 
identifiers are returned by dglope. 

DESCRIPTION 

dglclo closes the connection to the graphics server associated with the 
server identifier sid f killing the Distributed Graphics Library (DGL) 
server process and all its windows. If sid is negative, then all graphics 
server connections are closed. Call dglclo after gexit or when the graph- 
ics server is no longer needed. Closing the connection frees up 
resources on the graphics server. 

After a connection is closed, there is no current graphics window and no 
current graphics server. Calling any routines other than dglope, dglclo 
or routines that take graphics window identifiers as input parameters 
will result in an error. 

SEE ALSO 

dglope 

4Sight User's Guide, "Using the GL/DGL Interfaces". 

NOTE 

This routine is available only in immediate mode. 
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NAME 

dglope - opens a DGL connection to a graphics server 

FORTRAN 77 SPECIFICATION 

integer*4 dglope(svname, length, type) 
character*(*) svname 
integer*4 length, type 



( 



PARAMETERS 

svname expects a variable containing the name of the graphics server 
to which you want to open a connection. 

For a successful connection, the username on the server must 
be equivalent (in the sense of rtogm(lC)) to the originating 
account; no provision is made for specifying a password. The 
remote username used is the same as the local username unless 
you specify a different remote username. To specify a dif- 
ferent remote username, the svname string should use the for- 
mat username@servername. 

For DECnet connections, if the server account has a password, 
this password must be specified using the format 
username password® servemame. This password is used only 
for opening the DECnet connection; the two accounts must 
still be equivalent in the rlogin sense. 

length expects the length of the string in svname. 

type expects a symbolic constant that specifies the kind of connec- 
tion. There are three defined constants for this parameter: 

DGLLOC indicates a direct connection to the local graphics 
hardware. 

DGLTSO indicates a remote connection via TCP/IP. 

DGL4DD indicates a remote connection via DECnet. 



c 



( 
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FUNCTION RETURN VALUE 

If the connection succeeds, the returned value of the function is a non- 
negative integer, serverid, that identifies the graphics server. If the con- 
nection failed, the returned value for the function is a negative integer. 
The absolute value of a negative returned value is either a standard error 
value (defined in <errno.h>) or one of several error returns associated 
specifically with dglope: 

ENODEV type is not a valid connection type. 

EACCESS login incorrect or permission denied. 

EMFILE too many graphics connections are currently open. 

EBUSY only one DGLLOCAL connection allowed. 

ENOPROTOOPT 

DGL service not found in /etc/services. 

ERANGE invalid or unrecognizable number representation. 

EPROTONOSUPPORT 

DGL version mismatch. 

ESRCH the window manager is not running on the server. 

DESCRIPTION 

dglope opens a Distributed Graphics Library (DGL) connection to a 
graphics server (svname). After a connection is open, all graphics input 
and output are directed to that connection. Graphics input and output 
continue to be directed to the connection until either the connection is 
closed, another connection is opened or a different connection is 
selected. A different connection can be selected by calling a subroutine 
that takes a graphics window identifier as an input parameter, eg. win- 
set. The server connection associated with that graphics window 
identifier becomes the current connection. To close a DGL connection, 
call dglclo with the server identifier returned by dglope. 
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SEE ALSO 

dglclo, finish, gflush, winope, winset 

rlogin(lC) in the IRIS-4D User's Reference Manual 

4Sight User's Guide, "Using the GL/DGL Interfaces". ^ 

NOTES 

This routine is available only in immediate mode. 

This routine is available in both the DGL and GL library. However, 
only a DGLLOC connection type is supported by the GL library. 



( 



( 
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NAME 

j 
dopup - displays the specified pop-up menu 

FORTRAN 77 SPECIFICATION 

integer*4 function dopup(pup) 
integer*4 pup 

PARAMETERS 

pup expects the identifier of the pop-up menu you want to display. 

FUNCTION RETURN VALUE 

The returned value of the function is the value of the item selected from 
the pop-up menu. If the user makes no menu selection, the returned 
value of the function is -1. 

DESCRIPTION 

dopup displays the specified pop-up menu until the user makes a selec- 
tion. If the calling program has the input focus, the menu is displayed 
and dopup returns the value resulting from the item selection. The value 
can be returned by a submenu, a function, or a number bound directly to 
an item. If no selection is made, dopup returns -1. 

When you first define the menu (using addtop) you specify the list of 
menu entries and their corresponding actions. See addtop for details. 

SEE ALSO 

addtop, freepu, newpup 

NOTE 

This routine is available only in immediate mode. 
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NAME 

double - sets the display mode to double buffer mode 

FORTRAN 77 SPECIFICATION 
subroutine double 

PARAMETERS 

none 

DESCRIPTION 

double sets the display mode to double buffer mode. It does not take 
effect until gconfi is called. In double buffer mode, the bitplanes are 
partitioned into two groups, the front bitplanes and the back bitplanes. 
Double buffer mode displays only the front bitplanes. Drawing routines 
normally update only the back bitplanes; frontb and backbu can over- 
ride the default. 

In double buffer mode, gconfi calls frontb(.FALSE.) and 
backbu(.TRUE.). f 

SEE ALSO 

backbu, frontb, gconfi, getbuf, getdis, RGBmod, single, swapbu 

NOTE 

This routine is available only in immediate mode. 



( 
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NAME 

draw, drawi, draws, draw2, draw2i, draw2s - draws a line 

FORTRAN 77 SPECIFICATION 

subroutine draw(x, y, z) 
real x, y, z 

subroutine drawi(x, y, z) 

integer*4 x, y, z 

subroutine draws(x, y, z) 
integer*2 x, y, z 

subroutine draw2(x, y) 
realx, y 

subroutine draw2i(x, y) 
integer*4 x, y 

subroutine draw2s(x, y) 
integer*2 x, y 

All of the above functions are functionally the same except for the type 
declarations of the parameters. In addition the draw2* routines assume 
a 2-D point instead of a 3-D point. 

PARAMETERS 

x expects the x coordinate of the point to which you want to draw a line 
segment. 

y expects the y coordinate of the point to which you want to draw a line 
segment. 

z expects the z coordinate of the point to which you want to draw a line 
segment. (Not used by 2-D subroutines.) 

DESCRIPTION 

draw connects the point x, y, z and the current graphics position with a 
line segment. It uses the current linestyle, linewidth, color (if in depth- 
cue mode, the depth-cued color is used), and writemask. 
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draw updates the current graphics position to the specified point. Do 
not place routines that invalidate the current graphics position within 
sequences of moves and draws. 

SEE ALSO g 

bgnlin, endlin, move, v V 

NOTE 

draw should not be used in new development. Rather, lines should be 
drawn using the high-performance v commands, surrounded by calls to 
bgnlin and endlin. 



c 



o 
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NAME 

drawmo - selects which GL framebuffer is drawable 

FORTRAN 77 SPECIFICATION 

subroutine drawmo(mode) 
integer*4 mode 

PARAMETERS 

mode expects the identifier of the framebuffer to which GL drawing 
commands are to be directed: 

NORMDR, which sets operations for the normal color and z 
buffer bitplanes. 

OVRDRW, which sets operations for the overlay bitplanes. 

UNDRDR, which sets operations for the underlay bitplanes. 

PUPDRW, which sets operations for the pop-up bitplanes. 

CURSDR, which sets operations for the cursor. 

DESCRIPTION 

The IRIS physical framebuffer is divided into 4 separate GL frame- 
buffers: pop-up, overlay, normal, and underlay, drawmo specifies 
which of these four buffers is currently being controlled and modified by 
GL drawing and mode commands. Because drawmo cannot be set to 
multiple framebuffers, GL drawing commands affect only one of the 
four GL framebuffers at a time. 

The way that GL modes interract with drawmo is both complex and 
significant to the GL programmer. For example, each framebuffer 
maintains its own current color and its own color map. but linewidth is 
shared among all framebuffers. In general, modes that determine what 
is to be drawn into the framebuffers are shared; modes that control 
framebuffer resources are either multiply specified, or specified only for 
the normal framebuffer. 
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A separate version of each of the following modes is maintained by each 
GL framebuffer. These modes are modified and read back based on the 
current draw mode: 

backbu 

cmode ^ 

color or RGBcol |^ 

double 

frontb 

mapcol (a separate color map per framebuffer) 

readso 

RGBmod 

single 

writem or RGBwri 

The following modes currently affect only the operation of the normal 
framebuffer. They must therefore be modified only while draw mode is 
NORMAL. As features are added to the GL, these modes may become 
available in other draw modes. When this happens, a separate mode 
will be maintained for each draw mode. 

acsize 

blink f 

cyclem ^ 

multim 

onemap 

setmap 

stenci 

stensi 

swrite 

zbuffe 

zdraw 

zfunct 

zsourc 

zwrite 

All other modes, including matricies, viewports, graphics and character 
positions, lighting, and many primitive rendering options, are shared by 
the four GL framebuffers. | 
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Draw mode CURSDR differs from the others. True bitplanes for the 
cursor do not exist; there is no current color or writemask in this draw- 
ing mode. However, the cursor does have its own color map, and when 
in this mode, mapcol and getmco access it. 

SEE ALSO 

c, color, cpack, gconfi, getcol, getmco, getwri, mapcol, overla, stenci, 
underl, wmpack, writem 

NOTE 

This routine is available only in immediate mode. 

PUPDRAW mode is provided for compatibility, its use is discouraged. 

Some GL modes that are shared by all draw modes are not implemented 
by the popup, overlay, or underlay framebuffers. For example, the Per- 
sonal Iris does not do Gouraud shading in these framebuffers. It is 
important for the programmer to explicitly disable modes that are 
shared, but not desired, when in draw modes other than NORMAL. 
Otherwise the code may function differently on different platforms. 



Version 3.0 -3- April 1990 



editob Graphics Reference, FORTRAN editob 

NAME 

editob - opens an object definition for editing 

FORTRAN 77 SPECIFICATION 



c 



subroutine editob(obj) 
integer*4obj 

PARAMETERS 

obj expects object identifier for object definition you want to edit. 

DESCRIPTION 

editobj opens an object definition for editing. The system maintains an 
editing pointer that initially points to the end of the definition. The sys- 
tem appends all new routines at that pointer location until you call 
closeob or until you call a routine that repositions the editing pointer, 
such as obj del* objins, or objrep. 

Usually, you need not be concerned about memory allocation. Objects 
grow and shrink automatically as routines are added and deleted. (See I 
chunks.) ^ 

If you call editob for an undefined object identifier, the system displays 
an error message. 

SEE ALSO 

compac, objdel, objins, objrep, chunks 

NOTE 

This routine is available only in immediate mode. 



( 
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NAME 

bgnclo, endclo - delimit the vertices of a closed line 

FORTRAN 77 SPECIFICATION 
subroutine bgnclo 
subroutine endclo 

PARAMETERS 

none 

DESCRIPTION 

bgnclo marks the start of a group of vertex routines that you want inter- 
preted as points on a closed line. Use endclo to mark the end of the ver- 
tex routines that are part of the closed line. 

A closed line draws a line segment from one vertex on the list to the 
next vertex on the list. When the system reaches the end of the vertex 
list, it draws a line that connects the last vertex to the first vertex. All 
segments use the current linestyle, which is reset prior to the first seg- 
ment and continues through subsequent segments. To specify a vertex, 
use the v routine. 

Between bgnclo and endclo, you can issue only the following Graphics 
Library routines: c, color, cpack, Imbind, Imcolo, Imdef, n, RGBcol, t, 

and v. Within a closed line, you should use Imdef and Imbind only to 
respecify materials and their properties. If the color changes between a 
pair of vertices, the color of the line segment will be constant if the 
current shading model is FLAT and interpolated if the current shading 
model is GOURAU. In color map mode, the colors vary through the 
color map; to get reasonable results, the color map should contain a 
ramp. 

There is no limit to the number of vertices that can be specified between 
bgnclo and endclo. After endclo, the system draws a line from the final 
vertex back to the initial vertex, and the current graphics position is left 
undefined. 
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By default line vertices are forced to the nearest pixel center prior to 
scan conversion. Line accuracy is improved when this coercion is 
defeated with the subpix command. Subpixel vertex positioning is 
especially important when lines are scan converted with antialiasing 
enabled (see linesm). 

bgnclo/endclo are the same as bgnlin/endlin, except they connect the 
last vertex to the first. 

EXAMPLE 

The code fragment below draws the outline of a triangle. Lines use the 
current linestyle, which is reset prior to the first vertex and continues 
through all subsequent vertices. 

call bgnclo 
call v3f (vertl) 
call v3f (vert2) 
call v3f (vert3) 
call endclo 

SEE ALSO 

bgnlin, c, linesm, linewi, Isrepe, scrsub, setlin, shadem, subpix, v 

BUGS 

On the ERIS-4D B and G models, and on the Personal Iris without Turbo 
Graphics, if the color changes between a pair of vertices, the color of the 
line segment will be constant regardless of the current shading model. 

On the IRIS-4D GT and GTX models, if the color changes between a 
pair of vertices, the color of the line segment will be interpolated regard- 
less of the current shading model. 



c 



c 
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NAME 

feedba, endfee - control feedback mode 

FORTRAN 77 SPECIFICATION 

Personal Iris and IRIS-4DVGX: 
subroutine feedba(buffer, size) 
real buffer(size) 
integer*4 size 

integer*4 function endfee(buffer) 
real buffer(*) 

Other models: 

subroutine feedba(buffer, size) 
integer*2 buffer(size) 
integer*4 size 

integer*4 function endfee(buffer) 
integer*2 buffer(*) 

PARAMETERS 

buffer expects a buffer into which the system writes the feedback out- 
put from the Geometry Pipeline. On the Personal Iris and the 
IRIS-4D VGX, the output consists of 32-bit floating point 
values; on the other IRIS-4D models, the output consists of 16- 
bit integer values. Be sure you declare your buffer appropri- 
ately. 

size expects the maximum number of buffer elements into which the 
system will write feedback output. 

FUNCTION RETURN VALUE 

The return value of endfee is the actual number of elements of buffer 
that were written. The system will not write more than size elements, 
even when the amount of feedback exceeds it. You should assume that 
overflow has occurred whenever the return value is size. 
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DESCRIPTION 

feedba puts the system in feedback mode. In feedback mode, the sys- 
tem retains the output of the Geometry Pipeline rather than sending it to 
the rendering subsystem, endfee turns off feedback mode and returns 
the feedback output in buffer. This information is typically a descrip- 
tion of a vertex, and is machine specific. For information for interpret- 
ing the returned buffer, see the "Feedback" chapter of the Graphics 
Library Programming Guide . 

NOTE 

These routines are available only in immediate mode. 



c 



c 



( 
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NAME 

endful - ends fiiU-screen mode 

FORTRAN 77 SPECIFICATION 
subroutine endful 

PARAMETERS 

none 

DESCRIPTION 

endful ends full-screen mode and returns the screenmask and viewport 
to the boundaries of the current graphics window, endful leaves the 
current transformation unchanged. 

SEE ALSO 

fullscr 

NOTE 

This routine is available only in immediate mode. 
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NAME 

hgnlin, endlin - delimit the vertices of a line 

FORTRAN 77 SPECIFICATION 

subroutine bgnlin f 

subroutine endlin 

PARAMETERS 

none 

DESCRIPTION 

Vertices specified after bgnlin and before endlin are interpreted as end- 
points of a series of line segments. Use the v routine to specify a vertex. 
The first vertex connects to the second; the second connects to the third; 
and so on until the next-to-last vertex connects to the last one. The last 
vertex does not connect to the first vertex. Use bgnclo to connect the 
first and last points. All segments use the current linestyle, which is reset 
prior to the first segment and continues through subsequent segments. 

Between bgnlin and endlin, you can issue only the following Graphics 
Library routines: c, color, cpack, lmbind, lmcolo, Imdef, n, RGBcol, 
t, and v. Imdef and lmbind can be used to respecify only materials and 
their properties. If the color changes between a pair of vertices, the color 
of the line segment will be constant if the current shading model is 
FLAT and interpolated if the current shading model is GOURAU. In 
color map mode, the colors vary through the color map; to get reason- 
able results, the color map should contain a ramp. 

There is no limit to the number of vertices that can be specified between 
bgnlin and endlin. After endlin, the current graphics position is 
undefined. 

By default line vertices are forced to the nearest pixel center prior to 
scan conversion. Line accuracy is improved when this coercion is 
defeated with the subpix command. Subpixel vertex positioning is ^ 
especially important when lines are scan converted with antialiasing I 
enabled (see linesm). 



( 
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SEE ALSO 

bgnclo, c, linesm, linewi, lsrepe, scrsub, setlin, shadem, subpix, v 

BUGS 

On the IRIS-4D B and G models, and on the Personal Iris without Turbo 
Graphics, if the color changes between a pair of vertices, the color of the 
line segment will be constant regardless of the current shading model. 

On the IRIS-4D GT and GTX models, if the color changes between a 
pair of vertices, the color of the line segment will be interpolated regard- 
less of the current shading model. 
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NAME 

endpic - turns off picking mode 

FORTRAN 77 SPECIFICATION 

integer*4 function endpic(buffer) 
int£ger*2 buffer(*) 

PARAMETERS 

buffer expects a buffer into which to append the contents of the name 
stack when a drawing routine draws in the picking region. 
Before writing the contents of the name stack, the system 
appends the number of entries it is about to append. Thus, if the 
name stack contains the values, 5, 9, and 17; then endpic 
appends the values, 3, 5, 9, and 17, to buffer. 

Because more than one drawing routine may have written in the 
picking region, it is possible for buffer to contain a number of 
readings from the name stack. 

FUNCTION RETURN VALUE 

The returned value for the function is the number of times endpic wrote 
the names stack to buffer. 

If the returned function value is negative, then the buffer was too small 
to contain all the readings from the name stack. 

DESCRIPTION 

endpic turns off picking mode and writes the hits to a buffer. 

SEE ALSO 

initna, loadna, pick pushna, popnam 

NOTE 

This routine is available only in immediate mode. 



c 



c 



( 
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NAME 

bgnpoi, endpoi - delimit the interpretation of vertex routines as points 

FORTRAN 77 SPECIFICATION 
subroutine bgnpoi 
subroutine endpoi 

PARAMETERS 

none 

DESCRIPTION 

bgnpoi marks the beginning of a list of vertex routines that you want 
interpreted as points. Use the endpoi routine to mark the end of the list. 
For each vertex, the system draws a one-pixel point into the frame 
buffer. Use the v routine to specify a vertex. 

Between bgnpoi and endpoi, you can issue only the following Graphics 
Library routines: c, color, cpack, lmbind, lmcolo, Imdef, n, RGBcol, t, 
and v. Use lmdef and lmbind to respecify only materials and their pro- 
perties. 

There is no limit to the number of vertices that can be specified between 
bgnpoi and endpoi. 

By default points are forced to the nearest pixel center prior to scan 
conversion. This coercion is defeated with the subpix command. Sub- 
pixel point positioning is important only when points are scan converted 
with antialiasing enabled (see pntsmo). 

After endpoi, the current graphics position is the most recent vertex. 

SEE ALSO 

c, pntsmo, subpix, v 
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NAME 

bgnpol, endpol - delimit the vertices of a polygon 

FORTRAN 77 SPECIFICATION 

subroutine bgnpol I 

subroutine endpol 

PARAMETERS 
none 

DESCRIPTION 

Vertices specified after bgnpol and before endpol form a single 
polygon. The polygon can have no more than 256 vertices. Use the v 
subroutine to specify a vertex. Self-intersecting polygons (other than 
four-point bowties) may render incorrectly. Likewise, concave 
polygons may not render correctly if you have not called 
concav(.TRUE.). 

Between bgnpol and endpol, you can issue only the following Graphics f 
Library subroutines: c, color, cpack, Imbind, Imcolo, Imdef, n, V 
RGBcol, t, and v. Use Imdef and Imbind to respecify only materials 
and their properties. 

By default polygon vertices are forced to the nearest pixel center prior to 
scan conversion. Polygon accuracy is improved when this coercion is 
defeated with the subpix command. Subpixel vertex positioning is 
especially important when polygons are scan converted with antialiasing 
enabled (see polysm). 

After endpol, the current graphics position is undefined. 

SEE ALSO 

backfa, c, concav, frontf, polymo, polysm, scrsub, setpat, shadem, sub- 
pix, v 
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NOTES 

If you want to use the backfa or frontf routines, specify the vertices in 
counter-clockwise order. 

Although calling concav(.TRUE.) will guarantee that all polygons will 
be drawn correctly, on the IRIS-4D B and G models, and on the Per- 
sonal Iris, doing so cause their performance to be degraded. 
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NAME 

pupmod, endpup - obsolete routines 

FORTRAN 77 SPECIFICATION 

subroutine pupmod I 

subroutine endpup 

PARAMETERS 

none 

DESCRIPTION 

These routines are obsolete. Although pupmode/endpupmode con- 
tinue to function (to provide backwards compatibility) all new develop- 
ment should use drawmo to access the pop-up menu bitplanes. 



SEE ALSO 

drawmo 



c 



c 
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bgnqst, endqst - delimit the vertices of a quadrilateral strip 

FORTRAN SPECIFICATION 
subroutine bgnqst 
subroutine endqst 

DESCRIPTION 

Vertices specified between bgnqst and endqst are used to define a strip 
of quadrilaterals. The graphics pipe maintains three vertex registers. 
The first, second, and third vertices are loaded into the registers, but no 
quadrilateral is drawn until the system executes the fourth vertex rou- 
tine. Upon executing the fourth vertex routine, the system draws a qua- 
drilateral through the vertices, then replaces the two oldest vertices with 
the third and fourth vertices. 

For each new pair of vertex routines, the system draws a quadrilateral 
through two new vertices and the two older stored vertices, then replaces 
the older stored vertices with the two new vertices. 

Between bgnqst and endqst you can issue the following Graphics 
Library routines: c, color, cpack, lmbind, lmcolo, Imdef, n, RGBcol, 
t, and v. Use Imdef and lmbind only to respecify materials and their 
properties. 

If you want to use backfa, you should specify the vertices of the first 
quadrilateral in counter-clockwise order. All quadrilaterals in the strip 
have the same rotation as the first quadrilateral in a strip, so that back- 
facing works correctly. 

There is no limit to the number of vertices that can be specified between 
bgnqst and endqst. The result is undefined, however, if an odd number 
of vertices are specified, or if fewer than four vertices are specified. 

By default quadrilateral vertices are forced to the nearest pixel center 
prior to scan conversion. Quadrilateral accuracy is improved when this 
coercion is defeated with the subpix command. Subpixel vertex posi- 
tioning is especially important when quadrilaterals are scan converted 
with antialiasing enabled (see polysm). 
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After endqst the current graphics position is undefined. 

EXAMPLE 

For example, the code sequence: 

call bgnqst 
call v3f (zero) 
call v3f (one) 
call v3f (two) 
call v3f (three) 
call v3f (four) 
call v3f (five) 
call v3f (six) 
call v3f (seven) 
call endqst 

draws three quadrilaterals: (0,1,2,3), (2,3,4,5), and (4,5,6,7). Note that 
the vertex order required by quadrilateral strips matches the order 
required by the equivalent triangle mesh. The vertices above/when 
places between bgntme and endtme calls, draws six triangles: (0,1,2), 
(1,2,3), (2,3,4), (3,4,5), (4,5,6), and (5,6,7). 

SEE ALSO 

backfa, c, concav, frontf, polymo, polysm, scrsub, setpat, shadem, sub- 
pix,v 

NOTE 

IRIS-4D G, GT, and GTX models, and the Personal Iris, do not support 
quadrilateral strips. Use getgde to determine whether quadrilateral 
strips are supported. 

IRIS-4D VGX models use vertex normals to improve the shading qual- 
ity of quadrilaterals, regardless of whether lighting is enabled. 



c 



c 
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NAME 

endsel - turns off selecting mode 

FORTRAN 77 SPECIFICATION 

integer*4 function endsel(buffer) 
integer*2 buffer(*) 

PARAMETERS 

buffer expects a buffer into which to write hits. 

FUNCTION RETURN VALUE 

The returned function values is the number of hits made while selection 
mode was active. Each time there is a hit, the system writes the name 
stack to buffer. 

If the value returned is negative, the buffer is not large enough to hold 
all the hits that occurred. 

DESCRIPTION 

endsel turns off selection mode. The buffer stores any hits generated by 
drawing routines between gselec and endsel. Every hit that occurs 
causes the entire contents of the name stack to be recorded in the buffer, 
preceded by the number of names in the stack. Thus, if the name stack 
contains 5, 9, 17 when a hit occurs, the numbers 3, 5, 9, 17 are added to 
the buffer. 

SEE ALSO 

gselec, loadna, initna pushna, popnam 

NOTE 

This routine is available only in immediate mode. 
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NAME 

bgnsur , endsur - delimit a NURBS surface definition 

FORTRAN 77 SPECIFICATION 
subroutine bgnsur 
subroutine endsur 

PARAMETERS 

none 

DESCRIPTION 

Use bgnsur to mark the beginning of a NURBS (Non-Uniform Rational 
B-Spline) surface definition. After you call bgnsur, call the routines that 
define the surface and that provide the trimming information. To mark 
the end of a NURBS surface definition, call endsur. 

Within a NURBS surface definition (between bgnsur and endsur), you 
may use only the following Graphics Library subroutines: nurbss, 
bgntri, endtri, nurbsc, and pwlcur. The NURBS surface definition f 
must consist of exactly one call to nurbss to define the shape of the sur- ^ 
face. In addition, this call may be preceeded by calls to nurbss that 
specify how texture and color parameters vary across the surface. The 
call(s) to nurbss may be followed by a list of one or more trimming 
loop definitions (to define the boundaries of the surface). Each trim- 
ming loop definition consists of one call to bgntri, one or more calls to 
either pwlcur or nurbsc, and one call to endtri. 

The system renders a NURBS surface as a polygonal mesh, and calcu- 
lates normal vectors at the corners of the polygons within the mesh. 
Therefore, your program should specify a lighting model if it uses 
NURBS surfaces. If your program uses no lighting model, all the 
interesting surface information is lost When using a lighting model, 
use Imdef and Imbind to define or modify materials and their proper- 
ties. 



( 
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EXAMPLE 

The following code fragment draws a NURBS surface trimmed by two 
closed loops. The first closed loop is a single piecewise linear curve 
(see pwlcur), and the second closed loop consists of two NURBS curves 
(see nurbsc), joined end to end: 



call bgnsur 




call nurbss (. . . ) 




call bgntri 




call pwlcur (. . 


.) 


call endtri 




call bgntri 




call nurbsc (. . 


.) 


call nurbsc (. . 


-) 


call endtri 




call endsur 





SEE ALSO 

nurbss, bgntri, nurbsc, pwlcur, setnur, getnur 
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NAME 

bgntme, endtme - delimit the vertices of a triangle mesh 

FORTRAN 77 SPECIFICATION 
subroutine bgntme 
subroutine endtme 

PARAMETERS 

none 

DESCRIPTION 

Vertices specified between bgntme and endtme are used to define a 
mesh of triangles. The graphics pipe maintains two vertex registers. 
The first and second vertices are loaded into the registers, but no triangle 
is drawn until the system executes the third vertex routine. Upon execut- 
ing the third vertex routine, the system draws a triangle through the ver- 
tices, then replaces the older of the register vertices with the third ver- 
tex. 



c 



c 



For each new vertex routine, the system draws a triangle through the 
new vertex and the stored vertices, then (by default) replaces the older 
stored vertex with the new vertex. If you want the system to replace the 
more recent of the stored vertices, call swaptm prior to calling v. 

Between bgntme and endtme you can issue the following Graphics 
Library routines: c, color, cpack, Imbind, Imcolo, Imdef, n, RGBcol, 
swaptm, t, and v. Use Imdef and Imbind only to respecify materials 
and their properties. 

If you want to use backfa, you should specify the vertices of the first tri- 
angle in counter-clockwise order. All triangles in the mesh have the 
same rotation as the first triangle in a mesh so that backfacing works 
correctly. 

There is no limit to the number of vertices that can be specified between 
bgntme and endtme. £ 
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By default triangle vertices are forced to the nearest pixel center prior to 
scan conversion. Triangle accuracy is improved when this coercion is 
defeated with the subpix command. Subpixel vertex positioning is 
especially important when triangles are scan converted with antialiasing 
enabled (see polysm). 

After endtme the current graphics position is undefined. 

EXAMPLE 

For example, the code sequence: 

call bgntme 
call v3f (zero) 
call v3f (one) 
call v3f (two) 
call v3f (three) 
call endtme 

draws two triangles, (zero,one,two) and (one,two,three), while the code 
sequence: 

bgntme 
v3f (zero) 
v3f (one) 
swaptm 
v3f (two) 
v3f (three) 
endtme 

draws two triangles, (zero,one,two) and (zero,two,three). There is no 
limit to the number of times that swaptmesh can be called. 

SEE ALSO 

backfa, c, concav, frontf, polymo, polysm, scrsub, setpat, shadem, sub- 
pix, swaptm, v 
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NAME 

bgntri, endtri - delimit a NURBS surface trimming loop 

FORTRAN 77 SPECIFICATION 

subroutine bgntri I 

subroutine endtri 

PARAMETERS 

none 

DESCRIPTION 

Use bgntri to mark the beginning of a definition for a trimming loop. 
Use endtri to mark the end of a definition for a trimming loop. A trim- 
ming loop is a set of oriented curves (forming a closed curve) that 
defines boundaries of a NURBS surface. You include these trimming 
loop definitions in the definition of a NURBS surface. 

The definition for a NURBS surface may contain many trimming loops. 
For example, if you wrote a definition for NURBS surface that resem- 
bled a rectangle with a hole punched out, the definition would contain 
two trimming loops. One loop would define the outer edge of the rec- 
tangle. The other trimming loop would define the hole punched out of 
the rectangle. The definitions of each of these trimming loops would be 
bracketed by a bgntri/endtri pair. 

The definition of a single closed trimming loop may consist of multiple 
curve segments, each described as a piecewise linear curve (see pwlcur) 
or as a single NURBS curve (see nurbsc), or as a combination of both 
in any order. The only Graphics library calls that can appear in a trim- 
ming loop definition (between a call to bgntri and a call to endtri) are 
pwlcur and nurbsc. 



( 



c 
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In the following code fragment, we define a single trimming loop that 
consists of one piecewise linear curve and two NURBS curves: 

call bgntri 

call pwlcur(. . .) 

call nurbsc(. . .) 

call nurbsc(. . .) 
call endtri 

The area of the NURBS surface that the system displays is the region in 
the domain to the left of the trimming curve as the curve parameter 
increases. Thus, the resultant visible region of the NURBS surface is 
inside for a counter-clockwise trimming loop and outside for a clock- 
wise trimming loop. So for the rectangle mentioned earlier, the trim- 
ming loop for the outer edge of the rectangle should run counter- 
clockwise, and the trimming loop for the hole punched out should run 
clockwise. 

If you use more than one curve to define a single trimming loop, the 
curve segements must form a closed loop (i.e, the endpoint of each 
curve must be the starting point of the next curve, and the endpoint of 
the final curve must be the starting point of the first curve). If the end- 
points of the curve are sufficiently close together but not exactly coin- 
cident, the system coerces the them to match. If the endpoints are not 
sufficiently close, the system generates an error message and ignores the 
entire trimming loop. 

If a trimming loop definition contains multiple curves, the direction of 
the curves must be consistent (i.e., the inside must be to the left of the 
curves). Nested trimming loops are legal as long as the curve orienta- 
tions alternate correctly. If no trimming information is given for a 
NURBS surface, the entire surface is drawn. 

SEE ALSO 

bgnsur, nurbss, nurbsc, pwlcur, setnur, getnur 
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NAME 

feedba, endfee - control feedback mode 

FORTRAN 77 SPECIFICATION 

Personal Iris and IRIS-4D VGX: (^ 

subroutine feedba(buffer, size) 
real buffer(size) 
integer*4 size 

integer*4 function endfee(buffer) 
real buffer(*) 

Other models: 

subroutine feedba(buffer, size) 
integer*2 buffer(size) 
integer*4 size 

integer*4 function endfee(buffer) 
integer*2 buffer(*) 



PARAMETERS 

buffer expects a buffer into which the system writes the feedback out- 
put from the Geometry Pipeline. On the Personal Iris and the 
IRIS-4D VGX, the output consists of 32-bit floating point 
values; on the other IRIS-4D models, the output consists of 16- 
bit integer values. Be sure you declare your buffer appropri- 
ately. 

size expects the maximum number of buffer elements into which the 
system will write feedback output. 

FUNCTION RETURN VALUE 

The return value of endfee is the actual number of elements of buffer 
that were written. The system will not write more than size elements, 
even when the amount of feedback exceeds it. You should assume that 
overflow has occurred whenever the return value is size. 



c 
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DESCRIPTION 

feedba puts the system in feedback mode. In feedback mode, the sys- 
tem retains the output of the Geometry Pipeline rather than sending it to 
the rendering subsystem, endfee turns off feedback mode and returns 
the feedback output in buffer. This information is typically a descrip- 
tion of a vertex, and is machine specific. For information for interpret- 
ing the returned buffer, see the "Feedback" chapter of the Graphics 
Library Programming Guide. 

NOTE 

These routines are available only in immediate mode. 
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NAME 

finish - blocks until the Geometry Pipeline is empty 

FORTRAN 77 SPECIFICATION 
subroutine finish 

PARAMETERS 

none 

DESCRIPTION 

finish forces all unsent commands down the Geometry Pipeline to the 
rendering subsystem followed by a final token. It blocks the calling pro- 
cess until an acknowledgement is returned from the rendering subsystem 
that the final token has been received. 

SEE ALSO 

gflush ^ 

NOTE 

This routine is available only in immediate mode. 



c 
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NAME 

fogver - specify fog density forper-vertex atmospheric effects 

FORTRAN SPECIFICATION 

subroutine fogver(mode, params) 
integer*4 mode 
real paramsQ 

PARAMETERS 

mode expects one of three valid symbolic constants: 

FGDEFI: interpret params as a specification for fog density 
and color. 

FGON: enable the previously defined fog calculation 

FGOFF: disable fog calculations (default) 

params Expects an array of floats containing value settings. For 
FGDEFI four floats are expected. They are density, red, 
green, and blue, density specifies the (thickness) of the fog (or 
haze). A value of 0.0 results in no fog. Increasing positive 
values result in fog of increasing density. Values are normal- 
ized such that a density of 1.0 results in the fog becoming com- 
pletely opaque at a distance of 1.0 in eye-coordinates, red, 
green, and blue specify the fog color in the range 0.0 through 
1.0. ofshadem). 
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Calculation of the blend factor at each vertex uses the following equa- 
tion: 

Vfog = e ** (5.5*density*Zeye) 

Where: 

Vfog is the computed fog blending factor, ranging from to 1 . 

density is the fog density as specified when you call 

fogver (FGDEFI , params ) . 

z ey e is the Z coordinate in eye space (always negative). 

Vertex colors are first either Gouraud or flat shaded, then textured, 
before being blended with fog color. The pixel color/fog color blend is 
done with the following equation: 

C = Cp*Vfog + C£*(1.0-Vfog) 

Where: 

Vfog is the computed fog blending factor, ranging from to 1. 

C is the resulting color component (red, green, or blue). 

Cp is the incoming pixel color, already either Gouraud or flat 

shaded, and textured. 

Cf is the fog color component as specified when 

fogver (FGDEFI, params) is called. 

Eye-coordinates exist between ModelView transformation and Projec- 
tion transformation (see mmode). This space is right-handed, so visible 
vertices always have negative Z coordinates. Thus the Vfog equation 
always raises e to a negative power. 

The projection matrix must either be specified with a GL call (perspe, 
window, or ortho), or have as its final column the values: 

I o | 

I o | 

l-i I 

I o I 

In all cases (including ortho) the viewer is considered to be at location 
0,0,0, looking down the negative z axis. 
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SEE ALSO 

gRGBco, mmode 

NOTES 

IRIS-4D G, GT, and GTX models, and the Personal Iris, do not support 
fog. Use getgde to determine whether fog support is available. 

The results of fog calculations are defined only while in RGB mode. 
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NAME 

font - selects a raster font for drawing text strings 

FORTRAN 77 SPECIFICATION 

subroutine font(fntnum) £ 

integer*4 fntnum ^ 

PARAMETERS 

fntnum expects the font identifier, an index into the font table built by 
defras. If you specify a font number that is not defined, the 
system selects font 0. 

DESCRIPTION 

font selects the raster font that charst uses when it draws a text string. 
This font remains in effect until you call font again. Font is the 
default. 

SEE ALSO 

charst, defras, getdes, getfon, gethei, strwid I 



c 
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NAME 

foregr - prevents a graphical process from being put into the back- 
ground 

FORTRAN 77 SPECIFICATION 
subroutine foregr 

PARAMETERS 

none 

DESCRIPTION 

winope normally runs a process in the background. Call foregr before 
calling winope. It keeps the process in the foreground, so that you can 
interact with it from the keyboard. When the process is in the fore- 
ground, it interacts in the usual way with the IRIX input/output routines. 

SEE ALSO 

winope 

NOTE 

This routine is available only in immediate mode. 
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NAME 

freepu - deallocates a menu 

FORTRAN 77 SPECIFICATION 

subroutine freepu(pup) ■ 

integer*4pup 

PARAMETERS 

pup expects the menu identifier of the pop-up menu that you want to 
deallocate. 

DESCRIPTION 

freepu deallocates a pop-up menu, freeing the memory reserved for its 
data structures. 

SEE ALSO 

addtop, dopup, newpup 

c 

NOTE 

This routine is available only in immediate mode. 



( 
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NAME 

hackbu, frontb - enable and disable drawing to the back or front buffer 

FORTRAN 77 SPECIFICATION 

subroutine backbu(b) 
logical b 

subroutine frontb(b) 
logical b 

PARAMETERS 

h expects either .TRUE, or .FALSE.. 

.TRUE, enables updating in the back/front bitplane buffer. 
.FALSE, turns off updating in the back/front bitplane buffer. 

DESCRIPTION 

The IRIS framebuffer is divided into four separate GL framebuffers: 
pop-up, overlay, underlay, and normal. Three of these framebuffers, 
overlay, underlay, and normal, can be configured in double buffer mode. 
When so configured, a framebuffer includes two color bitplane buffers: 
one visible bitplane buffer, called the front buffer, and one non-visible 
bitplane buffer, called the back buffer. The commands swapbu and 
mswapb interchange the front and back buffer assignments. 

By default, when a framebuffer is configured in double buffer mode, 
drawing is enabled in the back buffer, and disabled in the front buffer. 
frontb and backbu enable and disable drawing into the front and back 
buffers, allowing the default to be overriden. Its is acceptable to enable 
neither front nor back, either front or back, or both front and back simul- 
taneously. Note, for example, that z-buffer drawing continues to update 
the z-buffer with depth values when neither the front buffer nor the back 
buffer is enabled for drawing. 

frontb and backbu state is maintained separately for each of the over- 
lay, underlay, and normal framebuffers. Calls to these routines affect 
the framebuffer that is currently active, based on the current drawmode. 
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backbu is ignored when the currently active framebuffer is in single 
buffer mode, frontb is also ignored when the currently active frame- 
buffer is in single buffer mode, unless zdraw is enabled for that frame- 
buffer (see zdraw). 

After each call to gconfi, backbu is enabled and frontb is disabled. 

SEE ALSO 

drawmo, double, getbuf, gconfi, single, swapbu, zdraw 



NOTE 



Only VGX graphics support double buffer operation in the overlay and 
underlay framebuffers. 



c 



c 



( 
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NAME 

frontf - turns frontf acing polygon removal on and off 

FORTRAN 77 SPECIFICATION 

subroutine frontf(b) 
logical b 

PARAMETERS 

h expects either .TRUE, or .FALSE.. 

.TRUE, suppresses the display of frontfacing filled polygons. 
.FALSE, allows the display of frontfacing filled polygons. 

DESCRIPTION 

frontf allows or suppresses the display of frontfacing filled polygons. If 
your programs represent solid objects as collections of polygons, you 
can use this routine to expose hidden surfaces. This routine works best 
for simple convex objects that do not obscure other objects. 

A frontfacing polygon is defined as a polygon whose vertices are in 
counter-clockwise order in screen coordinates. When frontfacing 
polygon removal is on, the system displays only polygons whose ver- 
tices are in clockwise order. For complicated objects, this routine alone 
may not expose all hidden surfaces. To expose hidden surfaces for more 
complicated objects or groups of objects, your routine needs to check 
the relative distances of the object from the viewer (z values). (See 
"Hidden Surface Removal" in the Graphics Library Programming 
Guide.) 

If frontf and backfa are asserted simultaneously, no filled polygons will 
be displayed. 

SEE ALSO 

backfa, zbuffe 
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NOTE 



On IRIS-4D G and B models frontf does not work well when a polygon 
shrinks to the point where its vertices are coincident. Under these con- 
ditions, the routine cannot determine the orientation of the polygon and 
so displays the polygon by default. £ ) 

On all IRIS-4D models matrices that negate coordinates, such as scale 
(-1.0, 1.0, 1.0), reverse the directional order of a polygon's points and 
can cause frontf to do the opposite of what is intended. 



( 
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NAME 

fudge - specifies fudge values that are added to a graphics window 

FORTRAN 77 SPECIFICATION 

subroutine fudge(xfudge, yfudge) 
integer*4 xfudge, yfudge 

PARAMETERS 

xfudge expects the number of pixels added in the x direction. 
yfudge expects the number of pixels added in the y direction. 

DESCRIPTION 

fudge specifies fudge values that are added to the dimensions of a 
graphics window when it is sized. Typically, you use it to create inte- 
rior window borders. Call fudge prior to calling winope. 

fudge is useful in conjunction with stepun and keepas. With stepunit 
the window size for integers m and n is: 

width = xunit x m + xfudge 
height = yunit xn + yfudge 

With keepas the window size is (width, height), where: 

(width - xfudge) x yaspect = (height - yfudge) x xaspect 

SEE ALSO 

keepas, stepun, winope 

NOTE 

This routine is available only in immediate mode. 
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NAME 

fullsc - allows a program write to the entire screen 

FORTRAN 77 SPECIFICATION 

subroutine fullsc m 

PARAMETERS 
none 

DESCRIPTION 

fullscr allows a program write to the entire screen. It does this by elim- 
inating the protections that normally prevent a graphics process from 
drawing outside of its current window. fullscr calls 
viewpo(0, getgde(GDXPMA)-!, 0, getgde(GDYPMA)-l) and ortho2 
to set up an orthographic projection that maps world coordinates to 
screen coordinates. The current viewport and matrix state are not saved; 
it is the caller's responsibility to do this. 

fullsc only affects graphics output; input focus management is f 

unchanged. V 

SEE ALSO 

endful, winope 

NOTES 

This routine is available only in immediate mode. 
Use fullsc with caution or a sense of humor. 



c 
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NAME 

gammar - defines a color map ramp for gamma correction 

FORTRAN 77 SPECIFICATION 

subroutine gammar(r, g, b) 
integer*2 r(256), g(256), b(256) 

PARAMETERS 

r expects an array of 256 elements. Each element contains a setting 
for the red electron gun. 

g expects an array of 256 elements. Each element contains a setting 
for the green electron gun. 

b expects an array of 256 elements. Each element contains a setting 
for the blue electron gun. 

DESCRIPTION 

gammar supplies a level of indirection for all color map and RGB 
values. For example, before the system would turn on the red gun to 
setting 238, the system looks in a table at location 238 and uses the 
value it finds there instead of 238. 

Thus, you can use this table to provide gamma correction, to equalize 
monitors with different color characteristics, or to modify the color 
warmth of the monitor. The default setting has r(7) = g(z) = b(0 = /. (So 
at location 238 of the red, green, and blue tables, you find the value 
238.) 

When the system is in RGB mode and draws an object, the system 
writes the actual red, green, and blue values to the bitplanes not the 
indirect values. However, the values that you see when the system 
draws the bitmap to the screen are the indirect values: r(red), g(green), 
b(blue) (where r,g,b are the arrays last specified by gammar). 

Similarly, when the system is in color map mode and draws an object, 
the system knows that the true color of the object may be color i, but to 
determine the displayed color, the system finds the red, green, and blue 
values of color i and displays color i as r(red), g(green), b(blue). 
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SEE ALSO 

color, cmode, mapcol, RGBcol 



NOTES 



This routine is available only in immediate mode. I 

On the IRIS-4D G, gamma correction in RGB mode uses the top 256 
entries of the colormap. 



( 
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NAME 

ginit, gbegin - create a window that occupies the entire screen 

FORTRAN 77 SPECIFICATION 
subroutine ginit 
subroutine gbegin 

PARAMETERS 

none 

DESCRIPTION 

ginit creates a window that covers the entire screen, and initializes its 
graphics state to the the same values as would a winope followed by a 
greset. It also sets the MOUSEX valuator to getgdesc(GDXPMA)/2 
with range to getgdesc(GDXPMA), and sets the MOUSEY valuator 
to with range to (etgdesc(GDYPMA)/2. gbegin does the same, 
except it does not alter the color map. 

These routines are a carry-over from the days before there was a window 
manager. Although they continue function, we recommend that all new 
development be designed to work with the window manager and to use 
winope. 

SEE ALSO 

greset, winope 

NOTE 

These routines are available only in immediate mode. 
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NAME 

gconfi - reconfigures the system 

FORTRAN 77 SPECIFICATION 

subroutine gconfi i 

PARAMETERS 

none 

DESCRIPTION 

gconfi sets the modes that you request. 

You must call gconfi for acsize, cmode, double, multim, onemap, 
overla, RGBmod, single, stensi, and underl to take effect. After a 
gconfi call, color for each draw mode is set to zero, and writemask for 
each draw mode is set to the number of bitplanes available in that draw 
mode. 

gconfi resolves mode requests for all draw modes, regardless of the 
current draw mode. 

SEEALSO 

acsize, cmode, double, multim, onemap, overla, RGBmod, single, 
stensi, underl 

NOTE 

This routine is available only in immediate mode. 



c 



( 
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NAME 

genobj - returns a unique integer for use as an object identifier 

FORTRAN 77 SPECIFICATION 
integer*4 function genobjO 

PARAMETERS 

none 

FUNCTION RETURN VALUE 

The returned value for this function is an object identifier. 

DESCRIPTION 

genobj generates unique 31 -bit integer numbers for use as object 
identifiers. Object identifiers can be up to 31 bits and must be unique 
within a program. Be careful if you use a combination of user-defined 
and genobj-defined numbers to generate object numbers, genobj will 
not generate an object name that is currently in use. If there is any ques- 
tion, use isobj before using your own numbers. 

SEE ALSO 

callob, gentag, isobj, makeob 

NOTE 

This routine is available only in immediate mode. 
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NAME 

gentag - returns a unique integer for use as a tag 

FORTRAN 77 SPECIFICATION 

integer*4 function gentagO ■ 

PARAMETERS 
none 

FUNCTION RETURN VALUE 

The returned value for this function is a tag number. 

DESCRIPTION 

gentag generates a unique integer to use as a tag. Tags must be unique 
within an object Although gentag generates unique tags, if you later 
define a tag with the same value, the first tag is lost. 

SEE ALSO f 

genobj,istag 

NOTE 

This routine is available only in immediate mode. 



c 
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NAME 

getbac - returns whether backfacing polygons will appear 

FORTRAN 77 SPECIFICATION 
integer*4 function getbac() 

PARAMETERS 

none 

FUNCTION RETURN VALUE 

The returned value for this function is either or 1 . 

indicates that backfacing polygon removal is turned off. 

1 indicates that backfacing polygon removal is enabled. 

DESCRIPTION 

getbac returns the state of backfacing filled polygon removal mode. If 
backface removal is enabled, the system draws only those polygons that 
face the viewer. 

SEE ALSO 
backfa 

NOTE 

This routine is available only in immediate mode. 
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NAME 

getbuf - indicates which buffers are enabled for writing 

FORTRAN 77 SPECIFICATION 

integer*4 function getbufQ f 

PARAMETERS 

none 

FUNCTION RETURN VALUE 

Individual bits in the returned value indicate which buffers are enabled. 
The bits are named: 



Symbolic Name Buffer Enabled 



BCKBUF back buffer 

FRNTBU front buffer 

DRA WZB zbuffer drawing 



DESCRIPTION f 

getbuf indicates which buffers are enabled for writing in double buffer 
mode. 

SEE ALSO 

backbu, double, frontb, zdraw 

NOTE 

This routine is available only in immediate mode. 

The symbolic return values mentioned above are defined in <gllfget.h> . 



( 
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NAME 

getbut - returns the state of a button 

FORTRAN 77 SPECIFICATION 

logical function getbut(num) 
integer*4 num 

PARAMETERS 

num is the device number of the button you want to test. 

FUNCTION RETURN VALUE 

There are two possible return values for this function: 

.FALSE, indicates that button num is up. 

.TRUE. indicates that button num is down. 

The return value is undefined if there was an error, e.g. num is not a 
button device. 

DESCRIPTION 

getbut returns the state of button num. 

NOTE 

This routine is available only in immediate mode. 
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NAME 

getcmm - returns the current color map mode 

FORTRAN 77 SPECIFICATION 
logical function getcmmQ 

PARAMETERS 

none 

FUNCTION RETURN VALUE 

There are two possible returned values for this function: 
.TRUE. indicates that onemap mode is active. 
.FALSE, indicates that multimap mode is active. 

DESCRIPTION 

getcmm returns the current color map mode. 

SEE ALSO 

multim, onemap 

NOTE 

This routine is available only in immediate mode. 



( 



( 



Version 3.0 -1- April 1990 



getcol Graphics Reference, FORTRAN getcol 

NAME 

getcol - returns the current color 

FORTRAN 77 SPECIFICATION 
integer*4 function getcol() 

PARAMETERS 

none 

FUNCTION RETURN VALUE 

Returns an index into the color map. 

DESCRIPTION 

getcol returns the current color for the current drawing mode. In 
NORMDR, it is an index into the color map, and is meaningful in both 
single and double buffer modes, getcol is ignored in RGB mode. In 
OVRDRW mode, getcol returns the color that is drawn into the overlay 
bitplanes, etc. 

SEE ALSO 

color, double, drawmo, getmco, single 

NOTE 

This routine is available only in immediate mode. 
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NAME 

getcpo - returns the current character position 

FORTRAN 77 SPECIFICATION 

subroutine getcpo(ix, iy) 
integer*! ix, iy 

PARAMETERS 

ix expects the variable into which to write the x coordinate of the 
current character position. 

iy expects the variable into which to write the y coordinate of the 
current character position. 

DESCRIPTION 

getcpos gets the current character position and writes it into the parame- 
ters. For purely historical reasons, the returned values are offset by the 
window origin; i.e. they are absolute screen coordinates. 

SEE ALSO 

charst, cmov, getgpo 

NOTE 

This routine is available only in immediate mode. 



c 



c 



( 
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NAME 

getcur - returns the cursor characteristics 

FORTRAN 77 SPECIFICATION 

subroutine getcur(index, color, wtm, b) 
integer*2 index, color, wtm 
logical b 

PARAMETERS 

index expects the variable into which the system writes the index of the 
current cursor. The cursor index is an index into a table of cursor 
bitmaps. 

color is an obsolete parameter. It is retained for compatibility with 
previous releases. 

wtm is an obsolete parameter. It is retained for compatibility with 
previous releases. 

b expects the variable into which the system returns a boolean indi- 
cating if the cursor in visible in the current window. 

DESCRIPTION 

getcur returns the index of the current cursor and a boolean value indi- 
cating if the cursor is visible in the current window. (The cursor will not 
be visible if cursof has been called.) 

SEE ALSO 

curson, defcur, setcur 

NOTE 

This routine is available only in immediate mode. 
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NAME 

getdcm - indicates whether depth-cue mode is on or off 

FORTRAN 77 SPECIFICATION 

logical function getdcmQ | 

PARAMETERS 

none 

FUNCTION RETURN VALUE 

This function can return either of two possible values: 
.FALSE., indicating that the system is not in depth-cue mode. 
.TRUE., indicating that the system is in depth-cue mode. 

DESCRIPTION 

getdcm tells you whether or not the system is in depth-cue mode. 

SEE ALSO V 

depthc 

NOTE 

This routine is available only in immediate mode. 



( 
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NAME 

getdep - obsolete routine 

FORTRAN 77 SPECIFICATION 

subroutine getdep(near, far) 
integer*2 near, far 

PARAMETERS 

near expects a variable into which the system should write the distance 
of the near clipping plane. 

far expects a variable into which the system should write the distance 
of the far clipping plane. 

DESCRIPTION 

This routine is obsolete. It continues to function to provide backwards 
compatibility, but only for depth values set with the obsolete routine 
setdep. It is not guaranteed to correctly return the depth values passed 
to lsetde, even when they do not exceed 16 bits. 

SEE ALSO 
lsetde, setdep 

NOTE 

This routine is available only in immediate mode. 
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NAME 

getdes - returns the character characteristics 

FORTRAN 77 SPECIFICATION 

integer*4 function getdes() f 

PARAMETERS 

none 

FUNCTION RETURN VALUE 

The returned value of this function is the length (in pixels) of the longest 
descender in the current font 

DESCRIPTION 



getdes returns the maximum distance (in pixels) between the baseline of 
a character and the bottom of the bitmap for that character. 

Each character in a font is defined using a bitmap that is displayed rela- 
tive to the current character position. Vertical placement of each char- 
acter is done using the current character position as the baseline or the 
line on the page. The portion of a character that extends below the base- 
line is called a descender. The lowercase characters g and p typically 
have descenders. 

SEE ALSO 

getfon, gethei, strwid 

NOTE 

This routine is available only in immediate mode. 



c 



c 
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NAME 

getdev - reads a list of valuators at one time 

FORTRAN 77 SPECIFICATION 

subroutine getdev(n, devs, vals) 

integer*4 n 

integer*2 devs(n), vals(n) 

PARAMETERS 

n expects the number of devices named in the devs array (no more 
than 128). 

devs expects an array containing the device identifiers (device number 
constants, such as MOUSEX, BPADX, LEFTMO etc.) of the dev- 
ices you want to read. This array can contain up to 128 devices. 

vals expects the array into which you want the system to write the 
values read from the devices listed in the devs array. Each 
member in the vals array corresponds to a member of the devs 
array. Thus, the value at vals(3) was read from the device named 
in devs(3). 

DESCRIPTION 

getdev allows you to read as many 128 valuators and buttons (input 
devices) at one time. 

SEE ALSO 

getval 

NOTE 

This routine is available only in immediate mode. 
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NAME 

getdis - returns the current display mode 

FORTRAN 77 SPECIFICATION 
integer*4 function getdis() 

PARAMETERS 

none 

FUNCTION RETURN VALUE 

The returned value for this function tells you which display mode is 
currently active. 



Symbolic Name 


Display Mode 


DMSING 


color map single buffer mode 


DMDOUB 


color map double buffer mode 


DMRGB 


RGB single buffer mode 


DMRGBD 


RGB double buffer mode 



DESCRIPTION 

getdis returns the current display mode. 

SEE ALSO 

cmode, double, RGBmod, single 

NOTE 

This routine is available only in immediate mode. 

The symbolic return values mentioned above are defined in <gllfget.h> . 



c 
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NAME 

getdra - returns the current drawing mode 

FORTRAN 77 SPECIFICATION 
integer*4 function getdra() 

PARAMETERS 

none 

FUNCTION RETURN VALUE 



Symbolic Name 


Drawing Mode 


NORMDR 


color planes 


OVRDRW 


overlay planes 


UNDRDR 


underlay planes 


PUPDRW 


pop-up planes 


CURSDR 


cursor 



DESCRIPTION 

getdra returns the current drawing mode. Use drawmo to set the draw- 
ing mode. 

SEE ALSO 

drawmo 

NOTE 

This routine is available only in immediate mode. 
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NAME 

getfon - returns the current raster font number 

FORTRAN 77 SPECIFICATION 

integer*4 function getfonQ f 

PARAMETERS 

none 

FUNCTION RETURN VALUE 

The returned value for this function is the index into the font table for 
the current raster font. 

DESCRIPTION 

getfont returns the index of the current raster font. 

SEE ALSO , 

defras, font V 

NOTE 

This routine is available only in immediate mode. 



( 
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NAME 

getgde - gets graphics system description 

FORTRAN 77 SPECIFICATION 

integer*4 function getgde(inquir) 
integer*4 inquir 

PARAMETERS 

inquiry expects the characteristic about which you want to inquire. 

FUNCTION RETURN VALUE 

The function returns the value of the requested characteristic, or -1, if 
the request is invalid or its value cannot be determined. 

DESCRIPTION 

getgde allows you to inquire about characteristics of the currently 
selected screen. You can call getgde prior to graphics initialization. 
Therefore, its return values are unaltered by any commands issued after 
initialization. 

The symbolic names of the inquiries and their meanings are specified 
below: 

Screen Boundary Inquiries 
GDXMMA 
GDYMMA 

Vertical and horizontal size of the screen in millimeters. 

GDXPMA 
GDYPMA 

Vertical and horizontal size of the screen in pixels. 

GDZMAX 
GDZMIN 

Maximum and minimum depth values that can be stored in the 
z-buffer of the normal framebuffer. 
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Framebuffer Depth Inquiries 
GDBIAC 

Number of bitplanes per color component in the hardware accu- 
mulation buffer, if one exists. Otherwise the number of bit- 
planes per color component in the software version of the accu- 
mulation buffer, if it is implemented. Otherwise 0. | 

GDBIAH 

Number of bitplanes per color component in the hardware accu- 
mulation buffer, if one exists. Otherwise 0. 

GDBCUR 

Number of bitplanes available in the cursor. 

GDBNDA 

Maximum number of bitplanes available in the normal frame- 
buffer to store alpha in double buffered RGB mode. 

GDBNDC 

Number of bitplanes available in the normal framebuffer to 
store the color index in double buffered color map mode. 

GDBNDM 

Number of bitplanes available in the normal framebuffer to 
store the color index in double buffered multimap mode. 

GDBNDR 
GDBNDG 
GDBNDB 

Number of bitplanes available in the normal framebuffer to 
store red, green, and blue in double buffered RGB mode. If any 
of these are 0, then double buffered RGB mode is not available. 

GDBNSA 

Maximum number of bitplanes available in the normal frame- 
buffer to store alpha in single buffered RGB mode. 

GDBNSC 

Maximum number of bitplanes available in the normal frame- 
buffer to store the color index in single buffered color map 
mode. 



( 
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NAME 

getgpo - gets the current graphics position 

FORTRAN 77 SPECIFICATION 

subroutine getgpo(fx, fy ? fz, fw) 
real fx, fy, fz, fw 

PARAMETERS 

fx expects the variable into which you want the system to write the x 
coordinate of the current graphics position. 

fy expects the variable into which you want the system to write the y 
coordinate of the current graphics position. 

fz expects the variable into which you want the system to write the z 
coordinate of the current graphics position. 

fw expects the variable into which you want the system to write the w 
coordinate of the current graphics position. The w value is used 
when defining a three dimensional point in homogeneous coordi- 
nates. 

DESCRIPTION 

getgpo returns the current graphics position after transformation by the 
current matrix. 

SEE ALSO 

getcpo 

NOTE 

This routine is available only in immediate mode. 
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NAME 

gethei - returns the maximum character height in the current raster font 

FORTRAN 77 SPECIFICATION 

integer*4 function getheiQ | 

PARAMETERS 

none 

FUNCTION RETURN VALUE 

The returned value of this function is the maximum height (in pixels) of 
a character in the current font. 

DESCRIPTION 

gethei returns the maximum height of the characters, in the current ras- 
ter font. The height is defined as the number of pixels between the top 
of the tallest ascender (in characters such as / and h) and the bottom of 
the lowest descender (in characters such as y and p). f 

SEE ALSO 

getdes, getfon, strwid 

NOTE 

This routine is available only in immediate mode. 



c 
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NAME 

gethit - returns the current hitcode 

FORTRAN 77 SPECIFICATION 
integer*4 function gethitQ 

PARAMETERS 

none 

DESCRIPTION 

gethit returns the global variable hitcode, which keeps a cumulative 
record of clipping plane hits. It does not change the hitcode value. 

The hitcode is a 6-bit number, with one bit for each clipping plane: 

5 4 3 2 10 



far near top bottom right left 



SEE ALSO 

clearhitcode, gselect, pick 

NOTES 

This routine is available only in immediate mode. 

The symbolic values for the hitcode bits shown above are defined in 
<gl/fget.h>. 

This routine only functions on IRIS-4D B and G models, and therefore 
we advise against its use in new development. 
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NAME 

getlsb - has no function in the current system 

FORTRAN 77 SPECIFICATION 

logical function getlsbQ I 

PARAMETERS 
none 

FUNCTION RETURN VALUE 

The returned value of this function is the current state of linestyle 
backup mode. 

DESCRIPTION 

getlsb returns the current state of linestyle backup mode. .TRUE., indi- 
cates that the final two pixels of a line segment are always colored. 
.FALSE., the default, indicates that the linestyle determines whether the ^ 
last two pixels are colored. 1 

Use Isback to change the state of this mode. 

SEE ALSO 
Isback 

NOTES 

This routine is available only in immediate mode. 

This routine only functions on IRIS-4D B and G models, and therefore 
we advise against its use in new development. 



c 
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NAME 

getlsr - returns the linestyle repeat count 

FORTRAN 77 SPECIFICATION 
integer*4 function getlsr() 

PARAMETERS 

none 

FUNCTION RETURN VALUE 

The returned value of this function is the repeat factor for the current 
linestyle. 

DESCRIPTION 

getlsr returns the current linestyle repeat factor. To set (or reset) the 
current linestyle repeat factor, call lsrepe. 

SEE ALSO 

lsrepe 

NOTE 

This routine is available only in immediate mode. 
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NAME 

getlst - returns the current linestyle 

FORTRAN 77 SPECIFICATION 

integer*4 function getlst() \^_ 

PARAMETERS 

none 

FUNCTION RETURN VALUE 

The returned value of this function is the index into the linestyle table 
for the current linestyle. 

DESCRIPTION 

getlstyle returns the current linestyle. 

SEE ALSO r 

deflin, setlin ^ 

NOTE 

This routine is available only in immediate mode. 



( 
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NAME 

getlwi - returns the current linewidth 

FORTRAN 77 SPECIFICATION 
integer*4 function getlwi() 

PARAMETERS 
none 

FUNCTION RETURN VALUE 

The returned value of this function is the current linewidth in pixels. 

DESCRIPTION 

getlwi returns the current linewidth in pixels. 

SEE ALSO 

linewi 

NOTE 

This routine is available only in immediate mode. 
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NAME 

getmap - returns the number of the current color map 

FORTRAN 77 SPECIFICATION 

integer*4 function getmapO | 

PARAMETERS 

none 

FUNCTION RETURN VALUE 

The returned value of this function is the number of the current color 
map. 

DESCRIPTION 

getmap returns the number of the current color map as set by setmap in 
multimap mode. In onemap mode, getmap returns zero. 

SEE ALSO ( 

multim, onemap 

NOTE 

This routine is available only in immediate mode. 



( 
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NAME 

getmat - returns a copy of a transformation matrix 

FORTRAN 77 SPECIFICATION 

subroutine getmat(m) 
real m(4,4) 

PARAMETERS 

m expects an array into which to copy a matrix. 

DESCRIPTION 

getmat copies a transformation matrix into a user-specified array. When 
mmode is MSINGL, the matrix from the top of the single matrix stack 
is returned. When mmode is MVIEWI, the matrix from the top of the 
ModelView matrix stack is returned. When mmode is MPROJE, the 
projection matrix is returned. And when mmode is MTEXTU, the tex- 
ture matrix is returned. 

getmat does not alter the state of the graphics system. 

SEE ALSO 

loadma, mmode, multma, popmat, pushma 

NOTE 

This routine is available only in immediate mode. 
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NAME 

getmco - gets a copy of the RGB values for a color map entry 

FORTRAN 77 SPECIFICATION 

subroutine getmco(i, red, green, blue) f 

integer*4 i 

integer*2 red, green, blue 

PARAMETERS 

i expects an index into the color map 

r expects the variable into which you want to copy the red value of the 
color at the color map index specified by L 

g expects the variable into which you want to copy the green value of 
the color at the color map index specified by L 

b expects the variable into which you want to copy the blue value of 
the color at the color map index specified by L 



DESCRIPTION 

getmcolor gets the red, green, and blue components of a color map 
entry and copies them to the specified variables. 

SEE ALSO 

drawmo, mapcol, gRGBco 

NOTE 

This routine is available only in immediate mode. 



c 



c 
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NAME 

getmmo - returns the current matrix mode 

FORTRAN 77 SPECIFICATION 
integer*4 function getmmo() 

PARAMETERS 
none 

FUNCTION RETURN VALUE 

The returned value of this function is the current matrix mode. There 
are four possible values for this function. 

MSINGL indicates single matrix mode mode. 

MPROJE indicates projection matrix mode. 

MVIEWI indicates viewing matrix mode. 

MTEXTU indicates texture matrix mode. 

DESCRIPTION 

getmmo returns the current matrix mode. 

SEE ALSO 

mmode 

NOTE 

This routine is available only in immediate mode. 
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NAME 

getmon - returns the type of the current display monitor 

FORTRAN 77 SPECIFICATION 

integer*4 function getmonQ I 

PARAMETERS 

none 

FUNCTION RETURN VALUE 

The returned value of this function is the type of the current display 
monitor. 

DESCRIPTION 

getmonitor returns the type of the current display monitor. The possible 
return values are: 

HZ30 30Hz interlaced monitor f 

HZ30 30HZ noninterlaced with sync on green monitor ^ 

HZ60 60Hz noninterlaced monitor 

NTSC NTSC monitor 

PAL PAL or SECAM monitor 

STRJtECT 

monitor in stereo mode 

SEE ALSO 

getoth, setmon, setvid 

NOTES 

This routine is available only in immediate mode. 



( 
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The symbolic return values mentioned above are defined in <gl/fget.h> . 

This function returns the value set previously by setmon. It does not 
actually test the hardware. 
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NAME 

getnur - returns the current value of a trimmed NURBS surfaces 
display property 

FORTRAN 77 SPECIFICATION 

subroutine getnur 
integer*4 property 
real value 

PARAMETERS 

property expects the name of the property to be queried. 

value expects variable into which the system should write the value 
of the named property. 

DESCRIPTION 

The display of NURBS surfaces can be controlled in different ways. 
The following is a list of the display properties that can be affected. 

NERRO: If value is 1.0, some error checking is enabled. If error 
checking is disabled, the system runs slightly faster. The 
default value is 0.0. 

NPIXEL: The value is the maximum length, in pixels, of egdes of 
polygons on the screen used to render trimmed NURBS sur- 
faces. The default value is 50.0 pixels. 

SEE ALSO 

bgnsur, nurbss, bgntri, nurbsc, pwlcur, setnur 

NOTE 

This routine is available only in immediate mode. 



( 



c 



c 
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NAME 

getope - returns the identifier of the currently open object 

FORTRAN 77 SPECIFICATION 
integer*4 function getope() 

PARAMETERS 

none 

FUNCTION RETURN VALUE 

The returned value of this function is the object identifier of the 
currently open object. If no object is now open, the returned value is -1. 

DESCRIPTION 

getope returns the number of the object that is currently open for edit- 
ing. 

NOTE 

This routine is available only in immediate mode. 
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NAME 

getori - returns the position of a graphics window 

FORTRAN 77 SPECIFICATION 

subroutine getori(x, y) I 

integer*4 x, y 

PARAMETERS 

x expects a variable into which the system should copy the x position 
(in pixels) of the lower left comer of the graphics window. 

y expects a variable into which the system should copy the y position 
(in pixels) of the lower left corner of the graphics window. 

DESCRIPTION 

getori returns the position (in pixels) of the lower-left corner of a graph- 
ics window. Call getori after graphics initialization. 



SEE ALSO 

winope 

NOTE 

This routine is available only in immediate mode. 



c 



( 
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NAME 

getoth - obsolete routine 

FORTRAN 77 SPECIFICATION 
integer*4 function getoth() 

PARAMETERS 

none 

FUNCTION RETURN VALUE 

The return value of this function indicates if the optional Composite 
Video and Genlock Board is installed in the system. 

DESCRIPTION 

This routine is obsolete. Although it continues to function to provide 
backwards compatibility, all new development should use 
getvid(CGMODE) to determine if the optional Composite Video and 
Genlock Board is installed in the system. 

SEE ALSO 

getvid 

NOTE 

This routine is available only in immediate mode. 
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NAME 

getpat - returns the index of the current pattern 

FORTRAN 77 SPECIFICATION 

integer*4 function getpat | 

PARAMETERS 
none 

FUNCTION RETURN VALUE 

The returned value of this function is an index into the table of available 
patterns. 

DESCRIPTION 

getpat returns the index of the current pattern from the table of available 
patterns. 

SEE ALSO f 

defpat, setpat 

NOTE 

This routine is available only in immediate mode. 



( 
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NAME 

getpla - returns the number of available bitplanes 

FORTRAN 77 SPECIFICATION 
integer*4 function getpla() 

PARAMETERS 
none 

FUNCTION RETURN VALUE 

The returned value of this function is the number of bitplanes available 
for drawing under the current drawmode. 

DESCRIPTION 

getpla returns the number of bitplanes that are available for drawing 
under the current drawmode. When the drawmode is NORMDR, the 
result also depends on the current buffer mode and whether or not mul- 
timap mode is active. When the drawmode is CURSDR, getpla always 
returns 0, since no direct drawing can be done into the cursor planes. 

SEE ALSO 

cmode, drawmo, double, getgde, multim, onemap, overla, RGBmod, 
single, underl 

NOTE 

This routine is available only in immediate mode. 
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NAME 

getpor - obsolete routine 

FORTRAN 77 SPECIFICATION 

subroutine getpor(name, length) \^ 

character*(*) name 
integer*4 length 

PARAMETERS 

name expects the window title that is displayed on the left hand side 
of the title bar for the window. 

length expects the length of the string in name. 

DESCRIPTION 

This routine is obsolete. Although it continues to function to provide 
backwards compatibility, all new development should use its replace- 
ment, winope. ^ 

SEE ALSO 

winope 



c 
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NAME 

getres - returns the state of linestyle reset mode 

FORTRAN 77 SPECIFICATION 
logical function getres() 

PARAMETERS 
none 

FUNCTION RETURN VALUE 

The returned value of this function is the current state of linestyle reset 
mode. 

DESCRIPTION 

getres returns the current state of linestyle reset mode. .TRUE., indi- 
cates that the stippling of each segment of a line starts at the beginning 
of the linestyle pattern. .FALSE., indicates that the linestyle is not reset 
between segments, and the stippling of one segment continues from 
where it left off at the end of the previous segment. 

Use resell to change the state of this mode. 

SEE ALSO 

reset! 

NOTES 

This routine is available only in immediate mode. 

This routine only functions on IRIS-4D B and G models, and therefore 
we advise against its use in new development. 
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NAME 

getsb - read back the current computed screen bounding box 

FORTRAN SPECIFICATION 

subroutine getsb(left, right, bottom, top) |^ 

integer *4 left, right, bottom, top 

PARAMETERS 

left returns the window coordinate of the left-most pixel drawn 
while scrbox has been tracking. 

right returns the window coordinate of the right-most pixel drawn 
while scrbox has been tracking. 

bottom returns the window coordinate of the lowest pixel drawn while 
scrbox has been tracking. 

top returns the window coordinate of the highest pixel drawn while 
scrbox has been tracking. 

DESCRIPTION 

getsb returns the current screen bounding box. scrbox is the computed 
bounding box of all geometry (points, lines, polygons) in screen-space. 
The hardware updates the four values each time geometry is drawn 
(while scrbox is tracking). 

If left is greater than right, or bottom is greater than top, nothing has 
been drawn since scrbox was reset. 

SEE ALSO 

scrbox 

NOTE 

This routine is available only in immediate mode. 



( 



( 
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IRIS-4D G, GT, and GTX models, and the Personal Iris, do not support 
scrbox, and therefore do not support getsb. Use getgde to determine 
whether scrbox is supported. 
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NAME 

getscr - returns the current screen mask 

FORTRAN 77 SPECIFICATION 

subroutine getscr(left, right, bottom, top) | 

integer*2 left, right, bottom, top ^ 

PARAMETERS 

left expects the variable into which the system should copy the x 
coordinate (in pixels) of the left side of the current screen 
mask. 

right expects the variable into which the system should copy the x 
coordinate (in pixels) of the right side of the current screen 
mask. 

bottom expects the variable into which the system should copy the y 
coordinate (in pixels) of the bottom side of the current screen 
mask. 

top expects the variable into which the system should copy the y £ 
coordinate (in pixels) of the top side of the current screen mask. ^ 

DESCRIPTION 

getscr returns the screen coordinates of the current screen mask. 

SEE ALSO 

scrmas, popvie, pushvi 

NOTE 

This routine is available only in immediate mode. 



( 
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NAME 

getsha - obsolete routine 

FORTRAN 77 SPECIFICATION 
integer*4 function getsha() 

PARAMETERS 

none 

DESCRIPTION 

This routine is obsolete. Although it continues to function to provide 
backwards compatibility, all new development should use its identical 
replacement, getcolor. 

SEE ALSO 

getcolor 

NOTE 

This routine is available only in immediate mode. 
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NAME 

getsiz - returns the size of a graphics window 

FORTRAN 77 SPECIFICATION 

subroutine getsiz(x, y) 
integer*4 x, y 

PARAMETERS 

x expects a variable into which the system should copy the width (in 
pixels) of a graphics window. 

y expects a variable into which the system should copy the height (in 
pixels) of a graphics window. 

DESCRIPTION 

getsiz gets the dimensions (in pixels) of the graphics window used by a 
graphics program. Call getsiz after winope. 

SEE ALSO 

winope 

NOTE 

This routine is available only in immediate mode. 



c 



c 



c 
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NAME 

getsm - returns the current shading model 

FORTRAN 77 SPECIFICATION 
integer*4 function getsm() 

PARAMETERS 

none 

FUNCTION RETURN VALUE 

The returned value of this function indicates which shading model is 
now active. There are two possible return values: 

FLAT the system renders lines and filled polygons in a constant 

color. 

GOURAU the system renders lines and filled polygons with Gouraud 
shading. 

DESCRIPTION 

getsm returns the shading model that the system uses to render lines and 
filled polygons. 

SEE ALSO 

shadem 

NOTE 

This routine is available only in immediate mode. 
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NAME 

getval - returns the current state of a valuator 

FORTRAN 77 SPECIFICATION 

integer*4 function getval(dev) I 

integer*4 dev 

PARAMETERS 

dev expects the identifier of the device (e.g., MOUSEX, BPADX, etc.) 
from which you want to read. 

FUNCTION RETURN VALUE 

The returned value of this function is the value stored at the device 
named by the dev parameter. 

DESCRIPTION 

getval returns the current value (an integer) of the valuator dev. _ 

SEE ALSO 

getbut, qdevic, tie 

NOTE 

This routine is available only in immediate mode. 



c 
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NAME 

setvid, getvid - set and get video hardware registers 

FORTRAN 77 SPECIFICATION 

subroutine setvid(reg, value) 
integer*4 reg, value 

integer*4 function getvid(reg) 
integer*4 reg 

PARAMETERS 

reg expects the name of the register to access. 
value expects the value which is to be placed into reg. 

FUNCTION RETURN VALUE 

The returned value of getvid is the value read from register reg, or -1. 
-1 indicates that reg is not a valid register or that you queried a video 
register on a system without that particular board installed. 

DESCRIPTION 

setvid sets the specified video hardware register to the specified value. 
getvid returns the value of the specified video hardware register. 
Several different video boards are supported; the board names and regis- 
ter identifiers are listed below. 

Display Engine Board 
DE_R1 

CG2 Composite Video and Genlock Board 
CG_CONTROL 
CG_CPHASE 
CGJHPHASE 
CG MODE 
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VP1 Live Video Digitizer Board 
VP_ALPHA 
VPJBRITE 

VP_CMD 

VP_CONT f 

VP_DIGVAL {^ 

VP_FBXORG 

VP_FBYORG 

VP_FGMODE 

VP.GBXORG 

VP_GBYORG 

VP_HBLANK 

VP_HEIGHT 

VP_HUE 

VP.MAPADD 

VP_MAPBLUE 

VP_MAPGREEN 

VP_MAPRED 

VP_MAPSRC 

VP.MAPSTROBE 

VP_PIXCNT 

VP_SAT 

VP_STATUSO 

VP_STATUS1 

VP_VBLANK 

VP_WIDTH 

SEE ALSO 

getmon, getoth, setmon, videoc 

NOTES 

These routines are available only in immediate mode. 

The DE_R1 register is actually present only on the video board used in 

the IRIS-4D B, G, GT, and GTX models. It is emulated on all other g 

models. I 



( 
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The Live Video Digitizer is available as an option for IRIS-4D GTX 
models only. 

For C, the symbolic constants named above are defined in the files 
<gl/cg2vme.h> and <gl/vpl.h> . You will need to create your own ver- 
sions of them for FORTRAN 77. 
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NAME 

getvie - gets a copy of the dimensions of the current viewport 

FORTRAN 77 SPECIFICATION 

subroutine getvie(left, right, bottom, top) I 

integer*! left, right, bottom, top 

PARAMETERS 

left expects the variable into which the system should copy the x 
coordinate (in pixels) of the left side of the current view port. 

right expects the variable into which the system should copy the x 
coordinate (in pixels) of the right side of the current view port. 

bottom expects the variable into which the system should copy the y 
coordinate (in pixels) of the bottom side of the current view 
port. 

top expects the variable into which the system should copy the y 
coordinate (in pixels) of the top side of the current view port. 



DESCRIPTION 

getvie gets the dimensions of the current viewport and copies them to 
the variables specified as parameters. The current viewport is defined as 
the viewport at the top of the viewport stack. 

SEE ALSO 

popvie, pushvi, viewpo 

NOTE 

This routine is available only in immediate mode. 



c 



c 
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NAME 

getwri - returns the current writemask 

FORTRAN 77 SPECIFICATION 
integer*4 function getwriQ 

PARAMETERS 

none 

FUNCTION RETURN VALUE 

The returned value of this function is the current writemask for the 
current drawing mode. 

DESCRIPTION 

getwri returns the current writemask of the current drawing mode. Each 
bit in the writemask corresponds to an available bitplane. Thus, bit 2 
describes bitplane 2 and so on. When a bit is set to zero in the wri- 
temask, the corresponding bitplane is read only. This routine is 
undefined in RGB mode. 

SEE ALSO 

RGBwri, writem, drawmo 

NOTE 

This routine is available only in immediate mode. 
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NAME 

getwsc - returns the screen upon which the current window appears 

FORTRAN 77 SPECIFICATION 

integer*4 function getwsc | 

PARAMETERS 

none 

FUNCTION RETURN VALUE 

The returned function value is the screen number upon which the current 
window appears. 

DESCRIPTION 

getwsc gets the screen number of the current window. 

NOTE 

This routine is available only in immediate mode. I 



c 
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NAME 

getzbu - returns whether z-buffering is on or off 

FORTRAN 77 SPECIFICATION 
logical function getzbu() 

PARAMETERS 
none 

FUNCTION RETURN VALUE 

The returned value of this function is either .TRUE, or .FALSE.. 

.TRUE, indicates that z-buffering is on. 

.FALSE, indicates that z-buffering is off. (.FALSE, is the default.) For 
systems without the zbuffer option, this function always returns 
.FALSE. 

DESCRIPTION 

getzbu returns the current value of the z-buffer flag. 

SEE ALSO 

Isetde zbuffe, zclear, 

NOTE 

This routine is available only in immediate mode. 
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NAME 

gexit - exits graphics 

FORTRAN 77 SPECIFICATION 

subroutine gexit |^ 

PARAMETERS 
none 

DESCRIPTION 

gexit closes all the windows of a process and then frees all Graphics 
Library data structures. Thereafter, the process can no longer call any 
routines that require the graphics to be initialized. 

gexit does not alter the image on screens for which the getgde inquiry 
GDSTYP returns GDSTNW. 

SEE ALSO f 

getgde, winclo V 

NOTE 

This routine is available only in immediate mode. 



c 
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NAME 

gflush - flushs the DGL client buffer 

FORTRAN 77 SPECIFICATION 
subroutine gflush 

PARAMETERS 

none 

DESCRIPTION 

gflush has no function in the Graphics Library, but is included to pro- 
vide compatibility with Distributed Graphics Library (DGL). 

SEE ALSO 
finish 
4Sight User's Guide, ' 'Using the GL/DGL Interfaces". 

NOTE 

The DGL on the client buffers the output from most graphics routines 
for efficient block transfer to the server. The DGL version of gflush 
sends all buffered bijt untransmitted graphics data to the server. Certain 
graphics routines, notably those that return values, also flush the client 
buffer when they execute. 
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NAME 

ginit, gbegin - create a window that occupies the entire screen 

FORTRAN 77 SPECIFICATION 
subroutine ginit 
subroutine gbegin 

PARAMETERS 

none 

DESCRIPTION 

ginit creates a window that covers the entire screen, and initializes its 
graphics state to the the same values as would a winope followed by a 
greset. It also sets the MOUSEX valuator to getgdesc(GDXPMA)/2 
with range to getgdesc(GDXPMA), and sets the MOUSEY valuator 
to with range to (etgdesc(GDYPMA)/2. gbegin does the same, 
except it does not alter the color map. 

These routines are a carry-over from the days before there was a window 
manager. Although they continue function, we recommend that all new 
development be designed to work with the window manager and to use 
winope. 

SEE ALSO 

greset, winope 

NOTE 

These routines are available only in immediate mode. 



c 



c 
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NAME 

glcomp - controls compatibility modes 

FORTRAN 77 SPECIFICATION 

subroutine glcomp(mode, value) 
integer*4 mode 
integer*4 value 

PARAMETERS 

mode the name of the compatibility mode you want to change. The 
available modes are: 

GLCOLD controls the state of old-style polygon mode. 

GLCZRA controls the state of z-range mapping mode. 

value the value you want to set for the specified compatibility mode. 

DESCRIPTION 

glcomp gives control over details of the graphics compatibility between 
IRIS-4D models. 

Old-Style Polygon Mode (GLCOLD) 

By default, old-style polygon mode is 1. Setting it to speeds up old- 
style drawing commands but the output is subtly different. See the 
"High-Performance Drawing" and "Old-Style Drawing" sections of 
the Graphics Library Programming Guide for further explanation of the 
two modes and their effects on various machines. 

WARNING: some features added recently to the Graphics Library are 
not supported by old-style polygons. These features include texture 
mapping, fog, and polygon antialiasing. Use new-style polygon com- 
mands, or set GLCOLD to 1, to insure correct operation of new render- 
ing features. 

This is a per-window mode. 
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Z-Range Mapping Mode (GLCZRA) 

When z-range mapping mode is 0, the domain of the z-range arguments 
to Isetde, lRGBra, and Ishade depends on the graphics hardware. The 
minimum is the value returned by getgde(GDZMIN) and the maximum 
is the value returned by getgde(GDZMAX). When this mode is 1 , these 
routines accept the range $0 to $7EFFFF; it is mapped to whatever range | 
the graphics hardware supports. ^ 

In order to maintain backwards compatibility, the default GLCZRA is 1 
on IRIS-4D B and G models, and on all others. 

This is a per-process mode. 

SEE ALSO 

getgde, lRGBra, Isetde, Ishade 

NOTES 

This routine is available only in immediate mode. 

The state of old-style polygon mode is ignored on IRIS-4D B and G 
models. _ 

BUG 

GLCZRA should be a per- window mode. 



( 
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NAME 

greset - resets graphics state 

FORTRAN 77 SPECIFICATION 
subroutine greset 

PARAMETERS 

none 

DESCRIPTION 

greset resets a portion of the graphics state of a window to its default. 

See the following table for a listing of the state affected. 
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State 


Value 


backface mode 


off 


blinking 


off 


buffer mode 


single 


color 


undefined 


color map mode 


one map 


concave 


off 


cursor 


(arrow) 


depth range 


Zmin,Zmax 


depthcue mode 


off 


display mode 


color map 


drawmode 


NORMDR 


font 





linestyle 


(solid) 


linewidth 


1 pixel 


Isrepeat 


1 


pattern 


(solid) 


picking size 


10x10 pixels 


RGB color 


undefined 


RGB shaderange 


undefined 


RGB writemask 


undefined 


shademodel 


GOURAU 


shaderange 


0,7 \Zmin,Zmax 


viewport 


entire screen 


writemask 


all planes enabled 


zbuffermode 


off 



c 



( 



Notes 

• Font is a Helvetica-like font. 

• Zmin and Zmax are the minimum and maximum values that you 
can store in the z-buffer. These depend on the graphics 
hardware and are returned by getgde(GDZMIN) and 
getgde(GDZMAX). 



On IRIS-4D B and G models, 
Isbackup(FALSE) and resetls(TRUE). 



greset also sets 
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greset loads a 2-D orthographic projection transformation on the matrix 
stack with left, right, bottom, and top set to the boundaries of the screen 
(not the current window). It also turns on the cursor. 

greset loads certain entries in the color map, as follows: 



Index 


Name 


RGB Value 


Red 


Green 


Blue 





BLACK 











1 


RED 


255 








2 


GREEN 





255 





3 


YELLOW 


255 


255 





4 


BLUE 








255 


5 


MAGENT 


255 





255 


6 


CYAN 





255 


255 


7 


WHITE 


255 


255 


255 


all others 


unnamed 




unchanged 





It loads the PUPDRW color map with the following entries: 



Index 


Name 


RGB Value 


Red 


Green Blue 


1 

2 
3 


PUPCOL 
PUPBLK 
PUPWHT 


255 


255 255 255 



It loads the CURSDR color map with the following entries: 



Index 


RGB Value 


Red 


Green Blue 


1 


255 


2 


255 255 255 


3 


255 



On systems that do not have a 2-plane cursor, only index 1 is loaded. 

SEE ALSO 

getgde 
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NOTES 

This routine is available only in immediate mode. 

greset sets the viewport and the projection transformation to values 
which assume that the current window occupies the entire screen, i.e. it 
was created via ginit or gbegin. If this is not the case, you will probably /^ 
want to call reshape and load a different projection transformation after V 
calling greset. 

This routine remains a part of the Graphics Library for reasons of back- 
wards compatibility only. We do not recommend the use of this routine 
in new development. 



c 



c 
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NAME 

gRGBco - gets the current RGB color values 

FORTRAN 77 SPECIFICATION 

subroutine gRGBco(red, green, blue) 
integer*2 red, green, blue 

PARAMETERS 

red expects the variable into which you want the system to copy the 
current red value. 

green expects the variable into which you want the system to copy the 
current green value. 

blue expects the variable into which you want the system to copy the 
current blue value. 

DESCRIPTION 

gRGBco gets the current RGB color values and copies them into the 
parameters. The system must be in RGB mode when you call gRGBco. 

SEE ALSO 

RGBcol, RGBmod, getmco 

NOTE 

This routine is available only in immediate mode. 
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NAME 

gRGBcu - obsolete routine 

FORTRAN SPECIFICATION 

subroutine gRGBcu(index, red, green, blue, redm, greenm, blueni, b) | 
integer*! index, red, green, blue, redm, greenm, bluem V 

logical b 

DESCRIPTION 

This routine is obsolete. It continues to function only on IRIS-4D B and 
G models to provide backwards compatibility. All new development 
should use its replacement, getcur. 

SEE ALSO 

getcur 



NOTE 

This routine is available only in immediate mode. 



c 



c 
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NAME 

gRGBma - returns the current RGB writemask 

FORTRAN 77 SPECIFICATION 

subroutine gRGBma(redm, greenm, bluem) 
integer*2 redm, greenm, bluem 

PARAMETERS 

redm expects the variable into which you want the system to copy 
the current red writemask value. 

greenm expects the variable into which you want the system to copy 
the current green writemask value. 

bluem expects the variable into which you want the system to copy 
the current blue writemask value. 

DESCRIPTION 

gRGBma gets the current RGB writemask as three 8-bit masks and 
copies them into the parameters. gRGBma places masks in the low 
order 8-bits of the variables. The system must be in RGB mode when 
this routine executes. 

SEE ALSO 

getwri, RGBwri 

NOTE 

This routine is available only in immediate mode. 
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NAME 

gselec - puts the system in selecting mode 

FORTRAN 77 SPECIFICATION 

subroutine gselec(buffer, numnam) f 

integer*2 buffer(*) 
integer*4 numnam 

PARAMETERS 

buffer expects the buffer into which you want the system to save the 
contents of the names stack, A name is a 16-bit number, that 
you load on the name stack just before you called a drawing 
routine. 

numnam expects the maximum number of names that you want the 
system to save. 

DESCRIPTION 

gselec turns on the selecting mode. When in selecting mode, the system ( 
notes when a drawing routine intersects the selecting region and writes ^- 
the contents of the names stack to the specified buffer. If you push a 
name onto the names stack just before you call each drawing routine, 
you can record which drawing routines intersected the selecting region. 

Use the current viewing matrix to define the selecting region. 

gselec and pick are identical except gselec allows you to create a view- 
ing matrix in selecting mode. To end select mode, call endsel. 

SEE ALSO 

endpic, endsel, pick, picksi, initna pushna, popnam, loadna 



NOTE 

This routine is available only in immediate mode. 



c 
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NAME 

gsync - waits for a vertical retrace period 

FORTRAN 77 SPECIFICATION 
subroutine gsync 

PARAMETERS 

none 

DESCRIPTION 

In single buffer mode, rapidly changing scenes should be synchronized 
with the refresh rate, gsync waits for the next vertical retrace period. 

SEE ALSO 

single 

NOTE 

This routine is available only in immediate mode. 
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NAME 

gversi - returns graphics hardware and library version information 

FORTRAN SPECIFICATION 

integer *4 function gversi(v) 
character*(*) v 

PARAMETERS 

v expects a variable into which to copy a string. Reserve at least a 

12 character buffer. 

FUNCTION RETURN VALUE 

There is no longer any use for the returned value of this function; it will 
always be zero. 

DESCRIPTION 

gversi fills the buffer, v, with a null-terminated string that specifies the 
graphics hardware type of the currently selected screen and the version f 
number of Graphics Library. V 

Graphics Type String Returned 

BorG GLAiy-m.n 

GT GL4DGT-m.n 

GTX GL4DGTX~-m.n 

VGX GL4DVGX-m.rc 

Personal Iris GL4DPI2-m.w 

Personal Iris with Turbo Graphics GL4DPIT-m.n 

Personal Iris (early serial numbers) GL4DPI-m.« 

m and n are the major and minor release numbers of the release to which 
the Graphics Library belongs. 

gversi can be called prior to the first winope. 



( 
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SEE ALSO 

scrnse, winope 

uname(2) in the Programmer's Reference Manual. 

NOTES 

This subroutine is available only in immediate mode. 

Early serial numbers of the Personal Iris do not support the complete 
Personal Iris graphics functionality. 
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NAME 

iconsi - specifies the icon size of a window 

FORTRAN 77 SPECIFICATION 

subroutine iconsi(x,y) 
integer*4 x, y 

PARAMETERS 

x expects the width (in pixels) for the icon. 
y expects the height (in pixels) for the icon. 

DESCRIPTION 

iconsi specifies the size (in pixels) of the window used to replace a 
stowed window. If a window has an icon size, the window manager will 
re-shape the window to be that size and send a REDRWI token to the 
graphics queue when the user stows that window. Your code can use an 
event loop to test for this token and can call graphics library subroutines 
to draw the icon for the stowed window. Windows without an icon size 
are handled by the window manager with the locally appropriate default 
behavior. 

To assign a new window an icon size, call iconsi before you open the 
window. To give an existing window an icon size, use iconsi with win- 
con. 

SEE ALSO 

qdevic, wincon, winope 

NOTES 

This routine is available only in immediate mode. 

Any application using iconsi should also call qdevic to queue the tokens 
WINFRE and WINTHA after opening the window. 



( 



( 



c 
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NAME 

iconti - assigns the icon title for the current graphics window. 

FORTRAN 77 SPECIFICATION 

subroutine iconti(name,length) 
character*(*) name 
integer*4 length 

PARAMETERS 

name expects a pointer to the string containing the icon title. 
length expects the length of the icon title string. 

DESCRIPTION 

iconti specifies the string displayed on an icon if the window manager 
draws that window's icon. 

SEE ALSO 
iconsi 
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NAME 

imakeb - registers the screen background process 

FORTRAN 77 SPECIFICATION 
subroutine imakeb 

PARAMETERS 
none 

DESCRIPTION 

imakeb registers a process that maintains the screen background. Call it 
before winope. The process should redraw the screen background each 
time it receives a REDRAW event. 

SEE ALSO 
winope 

NOTE (^ 

This routine is available only in immediate mode. 



( 
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NAME 

initna - initializes the name stack 

FORTRAN 77 SPECIFICATION 
subroutine initna 

PARAMETERS 

none 

DESCRIPTION 

initna clears the name stack for picking and selecting. 

SEE ALSO 

gselec, pick 
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NAME 

ismex - obsolete routine 

FORTRAN 77 SPECIFICATION 

logical function ismex() £ 

PARAMETERS 

none 

FUNCTION RETURN VALUE 

This routine returns .TRUE, if the 4Sight Window System is currently 
running. 

DESCRIPTION 

This routine is obsolete. Although it continues to function to provide 
backwards compatibility, all new development should test the return 
value of getgde(GDWSYS) to determine what window system is run- 
ning, f 

SEE ALSO 

getgde 

NOTE 

This routine is available only in immediate mode. 
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NAME 

isobj - returns whether an object exists 

FORTRAN 77 SPECIFICATION 

logical function isobj(obj) 
integer*4 obj 

PARAMETERS 

obj expects the object identifier that you want to test. 

FUNCTION RETURN VALUE 

There are two possible return values for this function: 
.TRUE. indicates that object obj exists. 
.FALSE. indicates that object obj does not exist. 

DESCRIPTION 

isobj returns whether or not an object exists. If makeob has been called 
to create an object, and delobj has not been called to delete it, isobj 
returns .TRUE, for it. 

SEE ALSO 

delobj, genobj, istag, makeob 

NOTE 

This routine is available only in immediate mode. 
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NAME 

isqueu -returns whether the specified device is enabled for queuing 

FORTRAN 77 SPECIFICATION 

logical function isqueu(dev) f 

integer*4 dev 

PARAMETERS 

dev expects the identifier for the device you want to test (e.g., 
MOUSEXorBPADX). 

FUNCTION RETURN VALUE 

The returned value for this function is a boolean value: 
.TRUE, indicates that dev is enabled for queueing. 
.FALSE, indicates that dev is not enabled for queueing. 

DESCRIPTION r 

isqueu returns whether or not the specified device is enabled for queue- V 
ing. 

SEE ALSO 

qdevic, unqdev, qread 

NOTE 

This routine is available only in immediate mode. 



c 
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NAME 

istag - returns whether a tag exists in the current open object 

FORTRAN 77 SPECIFICATION 

logical function istag(t) 
integer*4 1 

PARAMETERS 

t expects the tag identifier that you want to test., 

FUNCTION RETURN VALUE 

There are two possible return values for this function: 
.TRUE, indicates that tag t exists in the current open object. 
.FALSE. indicates that tag t does not exist in the current open object. 
The return value is undefined if no object is currently open for editing. 

DESCRIPTION 

istag returns whether or not a tag is exists in the object currently open 
for editing. If maketa has been called to create a tag, and deltag has not 
been called to delete it, istag returns .TRUE, for it. 

SEE ALSO 

deltag, gentag, isobj, maketa 

NOTE 

This routine is available only in immediate mode. 
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NAME 

keepas - specifies the aspect ratio of a graphics window 

FORTRAN SPECIFICATION 

subroutine keepas(x, y) f 

integer*4 x, y ^ 

PARAMETERS 

x expects the horizontal proportion of the aspect ratio. 
y expects the vertical proportion of the aspect ratio. 

DESCRIPTION 

keepas specifies the aspect ratio of a graphics window. Call it at the 
beginning of a graphics program. It takes effect when you call winope. 
The resulting graphics window maintains the aspect ratio specified in 
keepas, even if it changes size. 

For example, keepas(l, 1) always results in a square graphics window. 

You can also call keepas in conjunction with wihcon to modify the ■ 

enforced aspect ratio after the window has been created. 

SEE ALSO 

fudge, wincon, winope 

NOTE 

This routine is available only in immediate mode. 



( 
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NAME 

lampon, lampof - control the keyboard display lights 

FORTRAN 77 SPECIFICATION 

subroutine lampon(lamps) 
integer*4 lamps 

subroutine lampof(lamps) 
integer*4 lamps 

PARAMETERS 

lamps expects a mask that specifies which lamps to manipulate. The 
four low-order bits control the lamps labeled LI through L4. If a 
bit is set, then the corresponding keyboard lamp is turned on or 
off. 

DESCRIPTION 

lampon turns on any combination of the four user-controlled lamps on 
the keyboard and lampof turns them off. 

SEE ALSO 

clkon, ringbe, setbel 

NOTES 

This routine is available only in immediate mode. 

Future systems may not have these keyboard lights; therefore, we advise 
against the use of these routines for new development. 
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NAME 

linesm - specify antialiasing of lines 

FORTRAN 77 SPECIFICATION 

subroutine linesm(mode) I 

integer*4 mode 

PARAMETERS 

mode expects one of two values: 

SMLOFF, defeats antialiasing of lines (default). 

SMLON enables antialiasing of lines. SMLON can be modified 
by either or both of two additional symbolic constants: 

SMLSMO indicates that a higher quality filter should be used 
during line drawing. This filter typically requires that more pix- 
els be modified, and therefore potentially reduces the rate at 
which antialiased lines are rendered. 



SMLEND indicates that the endpoints of antialiased lines should 
be trimmed to the exact length specified by the subpixel position 
of each line. 

The constants SMLSMO and SMLEND are specified with SMLON by 
bitwise ORing them, or by adding them. For example, 

linesm (SMLON + SMLSMO + SMLEND) 

enables antialiased line drawing with the highest quality, and potentially 
lowest performance, algorithm. These modifiers are hints, not direc- 
tives, and are therefore ignored by systems that do not support the 
requested feature. 



c 



c 
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DESCRIPTION 

Antialiased lines can be drawn in both color map and RGB modes. 
linesm controls this capability. In both modes, for antialiased lines to 
draw properly: 

• line width must be 1 , 

• linestyle must be OxFFFF, 

• Isrepeat must be 1. 

For color map antialiased lines to draw correctly, a 16-entry colormap 
block (whose lowest entry location is a multiple of 16) must be initial- 
ized to a ramp between the background color (lowest index) and the line 
color (highest index). Before drawing lines, clear the area to the back- 
ground color. 

The linesmooth hardware replaces the least significant 4 bits of the 
current color index with bits that represent pixel coverage. Therefore, 
by changing the current color index (only the upper 8 bits are 
significant) you can select among many 16-entry color ramps, represent- 
ing different colors and intensities. You can draw depthcued, 
antialiased lines in this manner. 

The z-buffer hardware can be used to improve the quality of color map 
antialiased line images. Enabled in the standard depth-comparison 
mode, it ensures that lines nearer the viewer obscure more distant lines. 
Alternately, the z-buffer hardware can be used to compare color values 
by issuing: 

zbuffe(.TRUE.) 
zsourc (ZSRCCO) 
zf unct (ZFGREA) 

Pixels are then replaced only by 'brighter' values, resulting in better 
intersections between lines drawn using the same ramp. 

RGB antialiased lines can be drawn only on machines that support 
blending. For these lines to draw correctly, the blendfunction must be 
set to merge new pixel color components into the framebuffer using the 
incoming (source) alpha values. Incoming color components should 
always be multiplied by the source alpha (BFSA). Current (destination) 
color components can be multiplied either by one minus the source 
alpha (BFMSA), resulting in a weighted average blend, or by one 
(BFONE), resulting in color accumulation to saturation; issue: 
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weighted average 
blendf (BFSA, BFMSA) 



or 



c saturation 

blendf (BFSA, BFONE) 

The linesmooth hardware scales incoming alpha components by an 8 -bit 
computed coverage value. Therefore reducing the incoming source 
alpha results in transparent, antialiased lines. 

RGB antialiased lines draw correctly over any background image. It is 
not necessary to clear the area in which they are to be drawn. 

Both color map and RGB mode antialiased lines can be drawn with 
subpixel-positioned vertexes (see subpix). In general, subpixel posi- 
tioning of line vertexes results in higher quality but lower performance. 

The modifier SMLSMO can be ORed or ADDed to the symbolic con- 
stant SMLON when antialiased lines are enabled. When this is done, a 
higher quality and potentially lower performance filter is used to scan 
convert antialiased lines. SMLSMO is a hint, not a directive. Thus a 
higher quality filter is used only if it is available. 

The modifier SMLEND can ba ORed or ADDed to the symbolic con- 
stant SMLON when antialiased lines are enabled. When this is done, 
the endpoints of antialiased lines are scaled to the exact length specified 
by their subpixel-positioned endpoints, rather than drawn to the nearest 
integer length. SMLEND is a hint, not a directive. Thus antialiased 
lines are drawn with corrected endpoints only if support is available in 
the hardware. 

SEE ALSO 

bgnlin, blendf, deflin, linewi, Isrepe, pntsmo, v, subpix, zbuffe, zfunct, 
zsourc 

NOTES 

This subroutine does not function on IRIS-4D B or G models. 



c 



c 



( 
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IRIS-4D GT and GTX models, and the Personal Iris, do not support 
SMLSMO and SMLEND. Both hints are ignored on these systems. 

IRIS-4D VGX models adjust the antialiasing filter for each line based on 
its slope when SMLSMO is requested. They support SMLEND only in 
RGB mode. 



BUGS 



On the DRJS-4D GT and GTX models ZSRCCO z-buffering is supported 
only for non-subpixel positioned color map mode lines. 

Before ZSRCCO z-buffering is used on IRIS-4D GT and GTX models, 
bitplanes 12 through 23 must be explicitly cleared to zero. This must be 
done in RGB mode, with a code sequence such as: 

RGBmod() 

double () 

gconfi () 

f rontb ( . TRUE . ) 

cpack (0) 

clear () 

cmode ( ) 

f rontb (.FALSE.) 

gconfi () 

body of program 

The clear operation must be repeated only after bitplanes 12 through 23 
are modified, which can result only from interaction with another win- 
dow running in RGB mode. 
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NAME 

linewi - specifies width of lines 



subroutine linewi(n) | 



FORTRAN 77 SPECIFICATION 

subroutine 
integer*4 n 

PARAMETERS 

n expects the width of the line. The width is measured in pixels. 

DESCRIPTION 

linewi specifies the displayed width of a line. Mathematical lines have 
no width, but to display a line, you need to assign the line a width. As 
far as possible, the displayed line centers on the mathematical line. 
Because the pixels are arranged in a rectangular grid, only vertical and 
horizontal lines can have exactly the pixel width required. 

SEE ALSO 

setlin 

NOTE 

On IRIS-4D models that support resell, it must be set to TRUE, to 
obtain reasonable results with line widths greater than one. 



( 



( 
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NAME 

Imbind - selects a new material, light source, or lighting model 

FORTRAN 77 SPECIFICATION 

subroutine lmbind(target, index) 
integer*4 target, index 

PARAMETERS 

target expects one of these symbolic constants: MATERI, BACKMA, 
LIGHTO, LIGHT1, LIGHT2, LIGHT3, LIGHT4, LIGHTS, 
LIGHT6, LIGHT7, or LMODEL. 

index expects the name of a material (if target is MATERI or 
BACKMA), a light source (if target is one of LIGHTO through 
LIGHT7), or a lighting model (if target is LMODEL). Name 
is the index passed to Imdef when the material, light source, or 
lighting model was defined. 

DESCRIPTION 

Lighting operation is controlled by eleven lighting resources, each of 
which has a symbolic constant as a name. Imbind binds a material, 
light source, or lighting model definition to one of these eleven lighting 
resources. Its first argument, target, takes the symbolic name of a light- 
ing resource. Its second argument, index, takes the name of a lighting 
definition to be bound to that resource, index specifies a material 
definition if target is MATERI or BACKMA, a light source definition 
if target is LIGHTO through LIGHT7, or a lighting model definition if 
target is LMODEL. 

Two of these resources, MATERI and LMODEL, are special, in that 
they together determine whether lighting calculations are made or not. 
Lighting calculations are enabled when a material definition other than 
material is bound to MATERI, and a lighting model definition other 
than model is bound to LMODEL. When either MATERI is bound 
to material definition 0, or LMODEL is bound to lighting model 
definition 0, all lighting calculations are disabled. 
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Thus, for example, lighting is defined and enabled in the most primitive 
way by the following code sequence: 

lmdef (DEFMATL, 1,0, nullarray) 
lmde f ( DEF LMOL ,1,0, nullarray ) 
Imbind (MATERI,1) 
Imbind (LMODEL, 1) 

This primitive lighting model is disabled efficiently by simple binding 
material to MATERL 

Imbind (MATERI, 0) 

A lighting definition is unbound from a lighting resource only when 
another definition is bound to that resource. Changes made to a lighting 
definition while it is bound are effective immediately. By default all 
eleven lighting resources are bound to definition 0. If Imbind is passed 
a name that is not defined, definition is bound to the specified lighting 
resource. 

The eight fight sources, named LIGHTO through LIGHT7, are enabled 
when bound to a light source definition other than 0. Light source posi- 
tions are transformed by the current ModelView matrix when the source 
is bound. The object-coordinate position of the light source is main- 
tained in the definition so that subsequent bindings are transformed from 
it, rather than from the previously transformed position. A light source 
definition cannot be bound to more than one lighting resource in a single 
window. 



c 



( 



The default lighting model uses only a single material, namely the 
material definition that is bound to MATERI. Likewise, when a light- 
ing model with TWOSID specified is bound, MATERI is used for both 
front and back facing polygons if BACKMA is bound to material 
definition 0. However, if a material definition other than is bound to 
BACKMA, two-sided lighting uses MATERI for frontfacing polygons 
and BACKMA for backfacing polygons. In all cases points, lines, and 
characters are lighted using MATERI. 

Lighting models use only material and light properties that are appropri- 
ate to them. Other properties, such as color map mode properties while ^ 
the current framebuffer is in RGB mode, are ignored. 1 
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SEE ALSO 

Imcolo, lmdef, mmode, n, nmode 

NOTES 

Lighting requires that the matrix mode be multi-matrix. It does not 
operate correctly while mmode is MSINGL. 

ERIS-4D G, GT, and GTX models, and the Personal Iris, do not support 
two-sided lighting, and therefore do not support light resource 
BACKMA. 

It is a common error to bind a light source when an inappropriate 
ModelView matrix is on the stack. Be careful! 
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NAME 

lmcolo - change the effect of color commands while lighting is active 

FORTRAN 77 SPECIFICATION 

subroutine lmcolor(mode) 
integer*4 mode 

PARAMETERS 



c 



( 



mode the name of the mode to be used. Possible modes are: 

LMCCOL, RGB color commands will set the current color. If a 
color is the last thing sent before a vertex the vertex will be 
colored. If a normal is the last thing sent before a vertex the ver- 
tex will be lighted. LMCCOL is the default mode. 

LMCEMI, RGB color commands will set the EMISSI color 
property of the current material. 

LMCAMB, RGB color commands will set the AMBEEN color 
property of the current material. 

LMCDIF, RGB color commands will set the DIFFUS color 
property of the current material. Alpha, the fourth color com- 
ponent specified by RGB color commands will set the ALPHA 
property of the current material. 

LMCSPE, RGB color commands will set the SPECUL color 
property of the current material. 

LMCAD, RGB color commands will set the DIFFUS and 
AMBIEN color property of the current material. Alpha, the 
fourth color component specified by RGB color commands will 
set the ALPHA property of the current material. 

LMCNUL, RGB color commands will be ignored. 

DESCRIPTION 

Properties of the currently bound material can be changed by calls to | 
Imdef. Because the data structure of the material must be modified by ^ 
this operation, however, it is relatively slow to execute. Imcolo is pro- 
vided to support fast and efficient changes to the current material as 
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maintained in the graphics hardware, without changing the definition of 
the currently bound material. Thus lmcolo changes are lost whenever a 
new material is bound. 

The standard RGB color commands (RGBcol, c, and cpack) are used to 
change material properties efficiently. Imcolo specifies which material 
property is to be affected by these commands. While lighting is not 
active color commands change the current color. Imcolo mode is 
significant only while lighting is on. 

SEE ALSO 

Imdef, lmbind, RGBcol, c, cpack 

NOTE 

This routine is available only in immediate mode. 

Imcolo allows changes only to the properties of MATERI, not to the 
properties of BACKMA. 

While lmcolo is other than LMCNUL or LMCCOL, and lighting is 
active, the results of lighting are undefined between the time that a 
material is bound and an RGB color command is issued. 

While Imcolo is other than LMCNUL or LMCCOL, and lighting is 
active, the results of lighting are undefined if an RGB color command is 
specified between an n command and the subsequent v command. 
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NAME 

Imdef - defines or modifies a material, light source, or lighting model 



FORTRAN 77 SPECIFICATION 

subroutine lmdef(deftype, index, np, props) 
integer*4 deftype, index, np 
real props(np) 



( 



PARAMETERS 

deftype expects the category in which to create a new definition, or the 
category of the definition to be modified. There are three 
categories, each with its own symbolic constants: 

DEFMAT indicates that a material is being defined or 
modified. 

DEFLIG indicates that a light source is being defined or 
modified. 

DEFLMO indicates that a lighting model is being defined or 
modified. 

index expects the index into the table of stored definitions. There is a 
unique definitions table for each category of definition created 
by this routine (materials, light sources, or lighting models). 
Indexes within each of these categories are independent. In 
each category, index is reserved as a null definition, and can- 
not be redefined. 

np expects the number of symbols and floating point values in 

props, including the termination symbol LMNULL. If np is 
zero, it is ignored. Operation over network connections is 
more efficient when np is correctly specified, however. 

props expects the array of floating point symbols and values that 
define, or modify the definition of, the material, light source, or 
lighting model named index, props must contain a sequence of 
lighting symbols, each followed by the appropriate number of 
floating point values. The last symbol must be LMNULL, 
which is itself not followed by any values. 



( 



( 
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Different symbols are used to define materials, light sources, and light- 
ing models. The symbols used when deftype is DEFMAT are: 

ALPHA specifies the transparency of the material. It is followed by 
a single floating point value in the range 0.0 through 1.0. This alpha 
value is assigned to all RGB triples generated by the lighting model. 
Alpha is ignored by systems that do not support blending, and is 
always valid in systems that do, regardless of whether alpha bit- 
planes are installed in the system. The default alpha value is 1.0. 

AMBIEN specifies the ambient reflectance of the material. It is fol- 
lowed by three floating point values, typically in the range 0.0 
through 1.0, specifying red, green, and blue reflectances. The 
default ambient reflectances are 0.2, 0.2, and 0.2. 

COLORI specifies the material properties used when lighting in 
color map mode. This property is ignored while the current frame- 
buffer is in RGB mode, as are most other material properties when 
the current framebuffer is in color map mode. (Material property 
SHININ is used in color map mode.) It is followed by three floating 
point values, assigning the ambient, diffuse, and specular material 
color indices. The default color indices are 0.0, 127.5, and 255.0. 

DIFFUS specifies the diffuse reflectance of the material. It is fol- 
lowed by three floating point values, typically in the range 0.0 
through 1.0, specifying red, green, and blue diffuse reflectances. 
The default diffuse reflectances are 0.8, 0.8, and 0.8. 

EMISSI specifies the color of light emitted by the material. It is 
followed by three floating point values, typically in the range 0.0 
through 1.0, specifying red, green, and blue emitted light levels. 
The default emission levels are 0.0, 0.0, and 0.0. 

SHININ specifies the specular scattering exponent, or the shininess, 
of the material. It is followed by a single floating point value in the 
range 0.0 through 128.0. Higher values result in smaller, hence 
more shiny, specular highlights. The default shininess is 0.0, which 
effectively disables specular reflection. 

SPECUL specifies the specular reflectance of the material. It is fol- 
lowed by three floating point values, typically in the range 0.0 
through 1.0, specifying red, green, and blue specular reflectances. 
The default specular reflectances are 0.0, 0.0, and 0.0. 
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NAME 

loadma - loads a transformation matrix 

FORTRAN 77 SPECIFICATION 

subroutine loadma(m) I 

real m(4,4) 

PARAMETERS 

m expects the matrix which is to be loaded onto the matrix stack. 

DESCRIPTION 

loadma loads a 4x4 floating point matrix onto the transformation stack, 
replacing the current top matrix. 

SEE ALSO 

getmat, multma, popmat, pushma 



c 



( 
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NAME 

loadna - loads a name onto the name stack 

FORTRAN 77 SPECIFICATION 

subroutine loadna(name) 
integer*4 name 

PARAMETERS 

name expects the name which is to be loaded onto the name stack. 

DESCRIPTION 

loadna replaces the top name in the name stack with a new 16-bit 
integer name. Each time a routine causes a hit in picking or selecting 
mode, the system stores the contents of the name stack in a buffer. This 
enables the user to quickly identify the part of an image that appears 
near the cursor. 

SEE ALSO 

gselect, pick 
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NAME 

logico - specifies a logical operation for pixel writes 

FORTRAN 77 SPECIFICATION 

subroutine logico(opcode) I 

integer*4 opcode 

PARAMETERS 

opcode expects one of the 16 possible logical operations. 



Symbol 


Operation 


LOZERO 
LOAND 




src AND dst 


LOANDR 


src AND (NOT dst) 


LOSRC 


src 


LOANDI 


(NOT src) AND dst 


LODST 


dst 


LOXOR 


src XOR dst 


LOOR 


src OR dst 


LONOR 


NOT (src OR dst) 


LOXNOR 


not (src XOR dst) 


LONDST 


NOT dst 


LOORR 


src OR (NOT dst) 


LONSRC 


not src 


LOORI 


(NOT src) OR dst 


LONAND 


NOT (src AND dst) 


LOONE 


1 



( 



Only the lower 4 bits of opcode are used. 

The values of LOSRC and LODST have been chosen so that 
expressing an operation as the equivalent combination of them 
and the FORTRAN bit manipulation intrinsics generates an 
acceptable opcode value; e.g., LONAND can be written as 

NOT (I AND (LOSRC, LODST)). 
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DESCRIPTION 

logico specifies the bit-wise logical operation for pixel writes. The logi- 
cal operation is applied between the source pixel value (incoming value) 
and existing destination value (previous value) to generate the final pixel 
value. In colorindex mode all of the (up to 12) writemask enabled index 
bits are changed. In RGB mode all of the (up to 32) enabled component 
bits are changed. 

logico defaults to LOSRC, meaning that the incoming source value sim- 
ply replaces the current (destination) value. 

It is not possible to do logical operations and blend simultaneously. 
When opcode is set to any value other than LOSRC, the blendfunction 
sfactr and dfactr values are forced to BFONE and BFZERO repectively 
(their default values). Likewise, calling blendf with arguments other 
than BFONE and BFZERO forces the logical opcode to LOSRC. 

Unlike the blendfunction, logicop is valid in all drawing modes 
(NORMDR, UNDRDR, OVRDRW, PUPDRW, CURSDR) and in both 
colorindex and RGB modes. Like the blendfunction, it affects all draw- 
ing operations, including points, lines, polygons, and pixel area 
transfers. 

SEE ALSO 

blendf, gversi 

NOTES 

The numeric assignments of the 16 operation names were chosen to be 
identical to those defined by the X Window System. They will not be 
changed in future software releases. 

This routine does not function on DRIS-4D B, G, GT, and GTX models, 
nor does it function on early serial numbers of the Personal Iris. Use 
gversi to determine which type you have. 
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NAME 

lookat - defines a viewing transformation 

FORTRAN 77 SPECIFICATION 

subroutine lookat(vx, vy, vz, px, py, pz, twist) I 

real vx, vy , vz, px, py , pz 
integer*4 twist 

PARAMETERS 

vx expects the x coordinate of the viewing point, 

vy expects the y coordinate of the viewing point, 

vz expects the z coordinate of the viewing point. 

px expects the x coordinate of the reference point. 

py expects the y coordinate of the reference point. 

pz expects the z coordinate of the reference point 

twist expects the angle of rotation. 



c 



DESCRIPTION 

lookat defines the viewpoint and a reference point on the line of sight in 
world coordinates. The viewpoint is at (vx, vy, vz), and is the position 
from which you are looking. The reference point is at (px, py, pz), and is 
the location on which the viewpoint is centered. The viewpoint and 
reference point define the line of sight, twist measures right-hand rota- 
tion about the line of sight. 

The matrix computed by lookat premultiplies the current matrix, which 
is chosen based on the current matrix mode. 

SEE ALSO 

mmode, polarv 



( 
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NAME 

rectre, lrectr - reads a rectangular array of pixels into CPU memory 

FORTRAN 77 SPECIFICATION 

integer*4 rectre(xl, yl, x2, y2, parray) 
integer*4 xl, yl, x2, y2 
integer*2 parray(*) 

integer*4 Irectr(xl, yl, x2, y2, parray) 
integer*4 xl, yl, x2, y2 
integer*4 parray(*) 

PARAMETERS 

xl expects the x coordinate of the lower-left corner of the rectangle 
that you want to read. 

yl expects the y coordinate of the lower-left corner of the rectangle 
that you want to read. 

x2 expects the x coordinate of the upper-right corner of the rectan- 
gle that you want to read. 

y2 expects the y coordinate of the upper-right corner of the rectan- 
gle that you want to read. 

parray expects the array to receive the pixels that you want to read. 

FUNCTION RETURN VALUE 

The returned value of this function is the number of pixels specified in 
the rectangular region, regardless of whether the pixels were actually 
readable (i.e. on-screen) or not. 
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DESCRIPTION 

rectre and Irectr read the pixel values of a rectangular region of the 
screen and write them to the array, parray. The system fills the elements 
of parray from left-to-right, then bottom-to-top. All coordinates are 
relative to the lower-left comer of the window, not the screen or 
viewport. 

rectre fills an array of 16-bit words, and therefore should be used only 
to read color index values. Irectr fills an array of 32-bit words. Based 
on the current pixmod, in can return pixels of 1, 2, 4, 8, 12, 16, 24, or 32 
bits each. Use it to read packed RGB or RGBA values, color index 
values, or z values. Use readso to specify the pixel source from which 
both rectre and Irectr read pixels. 

pixmod greatly affects the operation of Irectr, and has no effect on the 
operation of rectre. By default, Irectr returns 32-bit pixels in the for- 
mat used by cpack. Different pixel sizes, framebuffer shifts, scan pat- 
terns through the framebuffer, and strides through memory, can all be 
specified using pixmod 

rectre and Irectr leave the current character position unpredictable. 

SEE ALSO 

Irectw, pixmod, readso 

NOTES 

These routines are available only in immediate mode. 

On IRIS-4D GT and GTX models, returned bits that do not correspond 
to valid bitplanes are undefined. Other models return zero in these bits. 

On IRIS-4D GT, GTX, and VGX models, rectre performance will 
suffer if x2 - xl + 1 is odd, or if parray is not 32-bit word aligned. 



c 
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NAME 

rectwr, Irectw - draws a rectangular array of pixels into the frame 
buffer 

FORTRAN 77 SPECIFICATION 

subroutine rectwr(xl, yl, x2, y2, parray) 
integer*4 xl, yl, x2, y2 
integer*2 parray(*) 

subroutine lrectw(xl, yl, x2, y2, parray) 
integer*4 xl, yl, x2, y2 
integer*4 parray(*) 

PARAMETERS 

xl expects the lower-left x coordinate of the rectangular region. 

yl expects the lower-left y coordinate of the rectangular region. 

x2 expects the upper-right x coordinate of the rectangular region. 

y2 expects the upper-right y coordinate of the rectangular region. 

parray expects the array which contains the values of the pixels to be 
drawn. For RGBA values, pack the bits thusly: $AABBGGRR, 
where: 

AA contains the alpha value, 
BB contains the blue value, 
GG contains the green value, and 
RR contains the red value. 

RGBA component values range from to $FF (255). The alpha 
value will be ignored if blending is not active and the machine 
has no alpha bitplanes. 

DESCRIPTION 

rectwr and Irectw draw pixels taken from the array parray into the 
specified rectangular frame buffer region. The system draws pixels left- 
to-right, then bottom-to-top. All coordinates are relative to the lower-left 
corner of the window, not the screen or viewport. All normal drawing 
modes apply. 
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The size of parray is always (x2-xl+l) x (y2-yl+l). If the zoom fac- 
tors set by rectzo are both 1.0, the screen region xl through x2, yl 
through y2, are filled. Other zoom factors result in filling past x2 and/or 
past y2 (xl,yl is always the lower-left corner of the filled region). 

rectwr draws an array of 16-bit words, and therefore should be used 
only to write color index values. Irectw draws an array of 32-bit words. 
Based on the current pixmod, in can draw pixels of 1, 2, 4, 8, 12, 16, 24, 
or 32 bits each. Use it to write packed RGB or RGBA values, color 
index values, or z values. 

* pixmod greatly affects the operation of Irectw, and has no effect on the 
operation of rectwr. By default, Irectw draws 32-bit pixels in the for- 
mat used by cpack. Different pixel sizes, framebuffer shifts, scan pat- 
terns through the framebuffer, and strides through memory, can all be 
specified using pixmod. 

rectwr and Irectw leave the current character position unpredictable. 

SEE ALSO 

blendf, Irectr, pixmod, rectco, rectzo 

NOTES 

These routines are available only in immediate mode. 



c 



c 



c 
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NAME 

IRGBra - sets the range of RGB colors used for depth-cueing 

FORTRAN 77 SPECIFICATION 

subroutine lRGBra(rmin, gmin, bmin, rmax, gmax, bmax, znear, zfar) 
integer*2 rmin, gmin, bmin, rmax, gmax, bmax 
integer*4 znear, zfar 

PARAMETERS 

rmin expects the minimum value to be stored in the red bitplanes. 

gmin expects the minimum value to be stored in the green bitplanes. 

hmin expects the minimum value to be stored in the blue bitplanes. 

rmax expects the maximum value to be stored in the red bitplanes. 

gmax expects the maximum value to be stored in the green bitplanes. 

bmax expects the maximum value to be stored in the blue bitplanes. 

znear expects the nearer screen z, to which the maximum colors are 
mapped. 

zfar expects the farther screen z, to which the minimum colors are 
mapped. 

DESCRIPTION 

IRGBra sets the range of RGB colors used for depth-cueing in RGB 
mode. The screen z range [znear, zfar] is mapped linearly into the RGB 
color range [ (rmax, gmax, bmax), (rmin, gmin, bmin) ]. Screen z values 
nearer than znear are mapped to (rmax, gmax, bmax); screen z values 
farther than zfar are mapped to (rmin ,gmin ,bmin) . 

The valid range for znear and zfar depends on the state of the GLCZRA 
compatibility mode (see glcomp). If it is 0, the valid range depends on 
the graphics hardware, where the minimum is the value returned by 
getgde(GDZMIN) and the maximum is the value returned by 
getgde(GDZMAX). If it is 1, the minimum is $0 and the maximum is 
$7FFFFF. Znear and zfar should be chosen to be consistent with the 
near and far parameters passed to lsetde. If near <far, then znear 
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should be less than zfar. If near > far, then znear should be greater 
than zfar. In either case, the range [near, far] should bound the range 
[znear, zfar]. 

SEE ALSO r 

depthc, getgde, glcomp, Isetde ^- 



( 



( 
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NAME 

lsback - controls whether the ends of a line segment are colored 

FORTRAN 77 SPECIFICATION 

subroutine lsback(b) 
logical b 

PARAMETERS 

b expects either .TRUE, or .FALSE.. 

.TRUE, forces the last pixel of a line segment to be colored. 

.FALSE, allows the linestyle to depend whether the last pixel of a 
line segment to be colored. 

DESCRIPTION 

lsback enables or disables linestyle backup mode. This mode controls 
how the final pixel of a line segment are rendered. If it is enabled, it 
causes the current linestyle to be overridden and forces the final pixel of 
a line segment to be colored. If it is disabled (the default), this does not 
happen, and line segments can have invisible endpoints. 

SEE ALSO 

deflin, getlsb, reset! 

NOTE 

This routine only functions on IRIS-4D B and G models, and therefore 
we advise against its use in new development. 
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NAME 

lsetde - sets the depth range 

FORTRAN SPECIFICATION 

subroutine lsetde(near 5 far) 
integer*4 near, far 

PARAMETERS 

near expects the screen coordinate of the near clipping plane. 
far expects the screen coordinate of the far clipping plane. 

DESCRIPTION 

viewpo specifies the mapping of the left, right, bottom, and top clipping 
planes into screen coordinates, lsetde completes this mapping for 
homogeneous world coordinates; it specifies the mapping of the near 
and far clipping planes into values stored in the z-buffer. 

Isetde is used in z-buffering, depth-cueing, and certain feedback appli- 
cations. 

The valid range of the parameters depends on the state of the GLCZRA 
compatibility mode (see glcomp). If it is 0, the valid range depends on 
the graphics hardware, where the minimum is the value returned by 
getgde(GDZMIN) and the maximum is the value returned by 
getgde(GDZMAX). If it is 1, the minimum is $0 and the maximum is 
$7FFFFF. The depth range defaults to the Ml range supported by the 
graphics hardware. 

Acceptable mappings include all those where both near and far are 
within the supported range, including mappings where near > far. In 
particular, it is sometimes desirable to call lsetde($7FFFFF 5 $0) on 
IRIS-4D GT and GTX models. 

SEE ALSO 

depthc, feedba, getgde, glcomp, zbuffe 



c 



c 



c 
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NOTE 



Error accumulation in the iteration of z can cause wrapping when the 
full depth range supported by the graphics hardware is used. (An itera- 
tion wraps when it accidentally converts an large positive value into a 
negative value, or vice versa.) While the effects of wrapping are typi- 
cally not observed, if they are, they can be eliminated by reducing the 
depth range by a small percentage. 
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NAME 

Ishade - sets range of color indices used for depth-cueing 

FORTRAN SPECIFICATION 

subroutine lshade(lowin ? highin, znear, zfar) I 

integer*2 lowin, highin ^ 

integer*4 znear, zfar 

PARAMETERS 

lowin expects the low-intensity color map index. 

highin expects the high-intensity color map index. 

znear expects the nearer screen z, to which highin is mapped. 

zfar expects the farther screen z, to which lowin is mapped. 



DESCRIPTION 

Ishade sets the range of color indices used for depth-cueing. The screen 
z range [znear, zfar] is mapped linearly into the color index range 
[highin, lowin]. Screen z values nearer than znear map to highin; 
screen z values farther than zfar map to lowin . 

The valid range for znear and zfar depends on the state of the GLCZRA 
compatibility mode (see glcomp). If it is 0, the valid range depends on 
the graphics hardware, where the minimum is the value returned by 
getgde(GDZMIN) and the maximum is the value returned by 
getgde(GDZMAX). If it is 1, the minimum is $0 and the maximum is 
$7FFFFF. The default is lshade(0, 7 9 Zmin 9 Zmax) t where Zmin and 
Zmax are the values such that the full range supported by the graphics 
hardware is used. 

Znear and zfar should be chosen to be consistent with the near mdfar 
parameters passed to lsetde. If near <far, then znear should be less 
than zfar. If near >far, then znear should be greater than zfar. In 
either case, the range [near, far] should bound the range [znear, zfar]. 



( 



( 
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SEE ALSO 

depthc, getgde, glcomp, lsetde 
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NAME 

Isrepe - sets a repeat factor for the current linestyle 

FORTRAN 77 SPECIFICATION 

subroutine Isrepe(factor) f ) 

integer*4 factor 

PARAMETERS 

factor expects the repeat factor of the linestyle pattern. The valid range 
ol factor is 1 through 255. 

DESCRIPTION 

Isrepe is used to create linestyles that are longer than 16 bits by multi- 
plying each bit in the pattern by factor. When a line is drawn, pixels are 
written if there is a 1 in the corresponding position of the linestyle mask 
and not written if there is a in the corresponding position. When 
Isrepe is used each bit in the pattern is multiplied successively by fac- 
tor. If the line pattern is 0000000111111111 and factor = 3, the result- f ) 
ing linestyle would be 27 bits on followed by 21 bits off. Line patterns V ; 
start from the least significant bit. 

SEE ALSO 
deflin, getlsr 



c 
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NAME 

makeob - creates an object 

FORTRAN 77 SPECIFICATION 

subroutine makeob(obj) 
integer*4 obj 

PARAMETERS 

obj expects the numeric identifier for the object being defined. 

DESCRIPTION 

makeob creates and names a new object by entering the identifier, 
specified by obj, into a symbol table and allocating memory for its list 
of drawing routines. If obj is the number of an existing object, the con- 
tents of that object are deleted. Drawing routines are then added into the 
display list instead of executing, until closeo is called. 

SEE ALSO 

callob, closeob, genobj, isobj, chunks 

NOTE 

This routine is available only in immediate mode. 
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NAME 

maketa - numbers a routine in the display list 

FORTRAN 77 SPECIFICATION 

subroutine maketa(t) I 

integer*4t 

PARAMETERS 

t expects a numeric identifier, or tag, which the system places between 
two list items. A tag locates display list items for editing. 

DESCRIPTION 

maketa places markers that identify specific locations of drawing rou- 
tines within an object definition. To do this, specify a 31 -bit number (t) 
with maketa. The system assigns this number to the next routine in the 
display list. A tag is specific only to the object in which you use it. Con- 
sequently, you can use the same 31 -bit number in different objects 
without confusion. £ 

SEE ALSO 

gentag, istag 



( 
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NAME 

mapcol - changes a color map entry 

FORTRAN 77 SPECIFICATION 

subroutine mapcol(i, red, green, blue) 
integer*4 i, red, green, blue 

PARAMETERS 

i expects the index into the color map. 

red expects an intensity value in the range to 255 for red to be 
associated with the index. 

green expects an intensity value in the range to 255 for green to be 
associated with the index. 

blue expects an intensity value in the range to 255 for blue to be 
associated with the index. 

DESCRIPTION 

mapcol loads entry i of the color map for the current drawing mode with 
{red, green, blue). Pixels written with color index i are displayed with 
the specified RGB intensities. The valid range for i depends on the 
number of bitplanes available in the current drawing and buffer modes, 
i.e. the value returned by getpla. Using Ni to represent 2 raised to the 
return value of getpla in drawing mode /, the valid ranges are: 

NORMDR OtoNn-l. 

OVRDRW ltoM>-l. 

UNDRDR OtoNu-1. 

PUPDRW ltoAfr-1. 

CURSOR 1 to getgde(GDBCUR). 

If Ni is 1, then no indices are valid. Invalid indices are ignored by 
mapcol. 

In multimap mode, mapcol updates only the small color map currently 
selected by setmap. 
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The color map entry that controls the color of the cross-hair cursor (cur- 
sor type CCROSS) is returned by the getgde inquiry GDXHCI. 

SEE ALSO 

color, cursty, drawmo, gammar, getgde, getmco, getpla, setmap 

NOTES 

This subroutine is available only in immediate mode. 

On the IRIS-4D G, you should not alter the top 256 colors (color indices 
3840 to 4095). The system uses these colors for the cursor, overlay bit- 
planes, and RGB mode. If you alter the colors to which these features 
are mapped, some screen features will appear in strange colors. 



c 



c 



c 



Version 3.0 - 2 - April 1 990 



mapw Graphics Reference, FORTRAN mapw 

NAME 

mapw - maps a point on the screen into a line in 3-D world coordinates 

FORTRAN 77 SPECIFICATION 

subroutine mapw(vobj, sx, sy, wxl, 
+ wyl, wzl, wx2, wy2, wz2) 

integer*4 vobj, sx, sy 
real wxl, wyl, wzl, wx2, wy2, wz2 

PARAMETERS 

vobj expects a viewing object containing the transformations that map 
the current displayed objects to the screen. 

sx expects the x coordinate of the screen point to be mapped. 

sy expects the y coordinate of the screen point to be mapped. 

wxl returns the x world coordinate of one endpoint of a line. 

wyl returns the y world coordinate of one endpoint of a line. 

wzl returns the z world coordinate of one endpoint of a line. 

wxl returns the x world coordinate of the remaining endpoint of a line. 

wy2 returns the y world coordinate of the remaining endpoint of a line. 

wzl returns the z world coordinate of the remaining endpoint of a line. 

DESCRIPTION 

mapw takes a pair of 2-D screen coordinates and maps them into 3-D 
world coordinates. Since the z coordinate is missing from the screen 
coordinate system, the point becomes a line in world space, mapw 
computes the inverse mapping from the viewing object, vobj. 

A viewing object is a graphical object that contains only viewport, pro- 
jection, viewing transformation, and modeling routines. A correct map- 
ping from screen coordinate to world coordinates requires that the view- 
ing object contain the projection and viewing transformations that 
mapped the displayed object from world to screen coordinates. 
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The system returns a world space line, which is computed from (sx, sy) 
and vohj, as two points and stores them in the locations addressed by 
wxl, wyl, wzl and wx2, wy2, wz2. 

SEE ALSO j- 

mapw2 V. 

NOTE 

This routine is available only in immediate mode. 



c 



c 
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NAME 

mapw2 - maps a point on the screen into 2-D world coordinates 

FORTRAN 77 SPECIFICATION 

subroutine mapw2(vobj, sx, sy, wx, wy) 
integer*4 vobj, sx, sy 
real wx, wy 

PARAMETERS 

vobj expects the transformations that map the displayed objects to 
world coordinates. 

sx expects the x coordinate of the screen point to be mapped. 

sy expects the y coordinate of the screen point to be mapped. 

wx returns the corresponding x world coordinate. 

wy returns the corresponding y world coordinate. 

DESCRIPTION 

mapw2 is the 2-D version of mapw. vobj is a viewing object contain- 
ing the viewport, projection, viewing, and modeling transformations that 
define world space, sx and sy define a point in screen coordinates, wx 
and wy return the corresponding world coordinates. If the transforma- 
tion is not 2-D, the result is undefined. 

SEE ALSO 

mapw 

NOTE 

This routine is available only in immediate mode. 
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NAME 

maxsiz - specifies the maximum size of a graphics window 

FORTRAN 77 SPECIFICATION 

subroutine maxsiz(x !> y) I 

integer*4 x, y 

PARAMETERS 

x expects the maximum width of a graphics window. The width is 
measured in pixels. 

y expects the maximum height of a graphics window. The height is 
measured in pixels. 

DESCRIPTION 



maxsiz specifies the maximum size (in pixels) of a graphics window. 
Call it at the beginning of a graphics program before winope. maxsiz 
takes effect when winope is called. 

You can also call maxsiz in conjunction with wincon to modify the 
enforced maximum size after the window has been created. The default 
maximum size is getgde(GDXPMA) pixels wide and 
getgde(GDYPMA) pixels high. The user can reshape the graphics win- 
dow, but the window manager does not allow it to become larger than 
the specified maximum size. 

SEE ALSO 

getgde, minsiz, winope 

NOTE 

This routine is available only in immediate mode. 



( 



( 
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NAME 

minsiz - specifies the minimum size of a graphics window 

FORTRAN 77 SPECIFICATION 

subroutine minsiz(x, y) 
integer*4 x, y 

PARAMETERS 

x expects the minimum width of a graphics window. The width is 
measured in pixels. The lowest legal value for this parameter is 1. 

y expects the minimum height of a graphics window. The height is 
measured in pixels. The lowest legal value for this parameter is 1. 

DESCRIPTION 

minsiz specifies the minimum size (in pixels) of a graphics window. 
Call it at the beginning of a graphics program. It takes effect when 
winope is called. You can also call minsiz with wincon to modify the 
enforced minimum size after the window has been created. The default 
minimum size is 40 pixels wide and 30 pixels high. You can reshape 
the window, but the window manager does not allow it to become 
smaller than the specified minimum size. 

SEE ALSO 

maxsiz, winope 

NOTE 

This routine is available only in immediate mode. 
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NAME 

mmode - sets the current matrix mode 

FORTRAN 77 SPECIFICATION 

subroutine mmode(m) 
integer*4 m 

PARAMETERS 

rn expects a symbolic constant, one of: 

MSINGL puts the system into single-matrix mode. In single-matrix 
mode, all modeling, viewing, and projection transformations are 
done using a single matrix that combines all these transformations. 
This is the default matrix mode. 

MVIEWI puts the system into multi-matrix mode. In this mode, 
separate ModelView, Projection, and Texture matrices are main- 
tained. The ModelView matrix is modified by all matrix operations. 

MPROJE puts the system into multi-matrix mode. In this mode, 
separate ModelView, Projection, and Texture matrices are main- I 
tained. The Projection matrix is modified by all matrix operations. 

MTEXTU puts the system into multi-matrix mode. In this mode, 
separate ModelView, Projection, and Texture matrices are main- 
tained. The Texture matrix is modified by all matrix operations. 

DESCRIPTION 

mmode specifies which matrix is the current matrix, and also deter- 
mines whether the system is in single -matrix mode, or in multi-matrix 
mode. The matrix mode and current matrix are determined as follows: 



o 
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mmode 



mmode 


matrix mode 


current matrix 


MSINGL 


single 


only matrix 


MVIEWI 


multi 


ModelView 


MPROJE 


multi 


Projection 


MTEXTU 


multi 


Texture 



In single-matrix mode, vertices are transformed directly from object- 
coordinates to clip-coordinates by a single matrix. All matrix com- 
mands operate on this, the only matrix. Single-matrix mode is the 
default mode, but its use is discouraged, because many of the newer GL 
rendering features cannot be used while the system is in single-matrix 
mode. 

In multi-matrix mode, vertices are transformed from object-coordinates 
to eye-coordinates by the ModelView matrix, then from eye-coordinates 
to clip-coordinates by the Projection matrix. A third matrix, the Texture 
matrix, is maintained to transform texture coordinates. While in multi- 
matrix mode, mmodes MVIEWI, MPROJE, and MTEXTU specify 
which of the three matrices is operated on by matrix modification com- 
mands. Many GL rendering operations, including lighting, texture map- 
ping, and user-defined clipping planes, require that the matrix mode be 
multi-matrix. 

Both the single matrix that is maintained while mmode is MSINGL 
mode, and the ModelView matrix that is maintained while not in 
MSINGL mode, have a stack depth of 32. The Projection and Texture 
matrices are not stacked. Thus matrix commands pushma and popmat 
should not be called while the matrix mode is MPROJE or MTEXTU. 

Changes between matrix modes MVIEWI, MPROJE and MTEXTU 
have no effect on the matrix values themselves. However, when matrix 
mode MSINGL is entered or left, all matrix stacks are forced to be 
empty, and all matrices are initialized to the identity matrix. 

SEE ALSO 

clippl, getmmo, lmbind, lookat, ortho, perspe, polarv, rot, rotate, scale, 
texbin, transl, window 
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BUGS 



On IRIS-4D G, GT, GTX systems, and on the Personal IRIS, multi- 
matrix operation is incorrect while mmode is MPROJE. Specifically, 
vertices are transformed only by the Projection matrix, not by the 
ModelView matrix. 



c 
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NAME 

move, movei, moves, move2, move2i, move2s - moves the current 
graphics position to a specified point 

FORTRAN 77 SPECIFICATION 

subroutine move(x, y, z) 
real x, y, z 

subroutine movei(x, y, z) 
integer*4 x, y, z 

subroutine moves(x, y, z) 
integer*2 x, y, z 

subroutine move2(x, y) 
real x, y 

subroutine move2i(x, y) 
integer*4 x, y 

subroutine move2s(x, y) 
integer*2 x, y 

All of the above routines are functionally the same. They differ only in 
the type declarations of their parameters and in whether they assume a 
three- or two-dimensional space. 

PARAMETERS 

x expects the new x coordinate for the current graphics position. 

y expects the new y coordinate for the current graphics position. 

z expects the new z coordinate for the current graphics position (when 
applicable). 

DESCRIPTION 

move changes (without drawing) the current graphics position to the 
point specified by x, y, and z. The graphics position is the point from 
which the next drawing routine will start drawing. 
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move2(x ? y) is equivalent to move(x, y, 0.0). 



SEE ALSO 

bgnlin, draw, endlin, v 



NOTE 



move should not be used in new development. Rather, lines should be 
drawn using the high-performance v commands, surrounded by calls to 
bgnlin and endlin. 
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NAME 

mswapb - swap multiple framebuffers simultaneously 

FORTRAN SPECIFICATION 

subroutine mswapb(fbuf) 
integer*4 fbuf 

PARAMETERS 

fbuf Expects a bitfield comprised of the logical OR of one or more of 
the following symbols: 

NORMAL indicates that the normal framebuffer is to be 
swapped. 

OVERDR indicates that the overlay framebuffer is to be 
swapped. 

UNDERD indicates that the underlay framebuffer is to be 
swapped. 

DESCRIPTION 

mswapb exchanges the front and back buffers of multiple framebuffers 
simultaneously. Which framebuffers are to have their buffers 
exchanged is specified by the bitfield fbuf the only argument. The nor- 
mal, overlay, and underlay framebuffers are specified with bitmasks 
NORMAL, OVERDR, and UNDERD. These masks must be ORed 
together to generate the fbuf argument. For example, both the normal 
and overlay framebuffers are swapped by the command: 
mswapb (NORMAL .OR. OVERDR). 

mswapb is executed during a vertical retrace period that closely follows 
the time of the request (usually the next vertical retrace). 

mswapb is ignored by framebuffers that are not in doublebuffer mode. 

SEE ALSO 

double, drawmo, swapbu, swapin 
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NOTES 

IRIS-4D models G, GT, and GTX, and the Personal Iris, do not imple- 
ment mswapb. 
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NAME 

multim - organizes the color map as a number of smaller maps 

FORTRAN 77 SPECIFICATION 
subroutine multim 

PARAMETERS 

none 

DESCRIPTION 

multim organizes the color map of the currently active framebuffer as a 
number of smaller maps. Because only the normal framebuffer supports 
multiple color maps, multim should be called only while drawmode is 
NORMAL. 

There are getgde(GDNMMA) maps, each of which will have up to 256 
entries, depending on the number of bitplanes available. Call getpla 
after setting the drawing mode to the desired framebuffer to determine 
the color map size, getgde can also be called at any time to determine 
the size of the color map of any framebuffer. 

multim does not take effect until gconfi is called. When called, gconfi 
executes multim requests pending for all drawing modes, regardless of 
the current drawing mode. 

A framebuffer's color map is used to display pixels only if the frame- 
buffer is in color map mode. 

SEE ALSO 

cmode, drawmo, gconfi, getgde, getcmm, getmap, onemap, setmap 

NOTE 

This routine is available only in immediate mode. 
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NAME 

multma - premultiplies the current transformation matrix 

FORTRAN 77 SPECIFICATION 

subroutine multma(m) f 

realm(4,4) 

PARAMETERS 

m expects the matrix that is to multiply the current top matrix of the 
transformation stack. 

DESCRIPTION 

multma premultiplies the current top of the transformation stack by the 
given matrix. If T is the current matrix, multma(M) replaces T with 
MxT. 

SEE ALSO 

getmat, loadma, popmat, pushma I 
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NAME 

n3f - specifies a normal 

FORTRAN SPECIFICATION 

subroutine n3f(vector) 
real vector(3) 

PARAMETERS 

vector expects an array containing three floating point numbers. These 
numbers are used to set the value for the current vertex normal. 

DESCRIPTION 

n3f specifies a floating point normal for lighting calculations. The nor- 
mal becomes the current normal for subsequent vertices; it is not neces- 
sary to respecify a normal if it is unchanged (e.g., a single call to n3f 
specifies normals for all vertices of a flat- shaded polygon). 

Vector components are Nx, Ny, and Nz for indices 1, 2, and 3. 

Lighting calculations assume that the specified normal is of unit length. 
If non-unit length normals are to be specified, use nmode to inform the 
system that normals must be normalized. Lighting performance may be 
reduced in this event. 

When called with unequal arguments, scale causes the Model View 
matrix to become nonorthonormal. In this case, or in any other case that 
results in a nonorthonormal ModelView matrix, normals are also renor- 
malized automatically. Performance reduction, if any, matches that of 
nmode user-specified normalization. 

SEE ALSO 

Imbind, lmdef, nmode 
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NAME 

newpup - allocates and initializes a structure for a new menu 

FORTRAN 77 SPECIFICATION 
integer*4 function newpupO 

PARAMETERS 

none 

FUNCTION RETURN VALUE 

The returned value of this function is a menu identifier. 

DESCRIPTION 

newpup allocates and initializes a structure for a new menu; it returns a 
positive menu identifier. Use to create pop-up menus. 

SEE ALSO 

newpup with addtop to create pop-up menus. 

SEE ALSO 

addtop, dopup, freepu 

NOTE 

This routine is available only in immediate mode. 



c 
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NAME 

newtag - creates a new tag within an object relative to an existing tag 

FORTRAN 77 SPECIFICATION 

subroutine newtag(newtg, oldtg, offst) 
integer*4 newtg, oldtg, offst 

PARAMETERS 

newtg expects an identifier for the tag that will be created. 

oldtg expects an existing tag. It will be used as a reference point for 
inserting newtg. 

offst expects the number of positions beyond oldtg where newtg. will 
be placed. 

DESCRIPTION 

newtag creates a new tag and places it at the specified number of posi- 
tions beyond oldtg. The number of positions is indicated by offst. 

newtag is used within an object after at least one tag has been created 
by calling maketa. 

SEE ALSO 

maketa 

NOTE 

This routine is available only in immediate mode. 
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NAME 

nmode - specify renormalization of normals 

FORTRAN SPECIFICATION 

subroutine nmode(mode) f 

integer*4 mode 

PARAMETERS 

mode expects a symbolic constant. There are two defined constants for 
this parameter: 

NAUTO causes normals to be renormalized only if the current 
ModelView matrix is not orthonormal. (default) 

NNORMALIZE causes normals to always be renormalized, 
regardless of the current ModelView matrix. 



DESCRIPTION 

IRIS systems transform vertex normals from object-coordinates to eye- 
coordinates before doing lighting calculations. While the matrix mode 
is MVIEWIN, a separate Normal matrix is maintained to support this 
transformation. The Normal matrix is the inverse transpose of the 
upper-left 3x3 portion of the ModelView matrix. 

Transformed normals must be unit length if the lighting calculations are 
to be meaningful. Transformed normals will be unit length if 1) they 
were unit length in object-coordinates, and 2) the current Normal matrix 
is orthonormal (see notes). If one or both of these conditions are not 
met, the normal must be normalized (corrected to have unit length) after 
it is transformed, nmode helps the system determine when normaliza- 
tion is required. 

Each time the ModelView matrix is changed, the IRIS determines 
whether the resulting (inverse-transpose) Normal matrix is orthonormal 
or not, and saves the result of the test as a flag. After each normal is 
transformed, both this flag and the nmode flag are tested. If nmode is 
NAUTO, the normal is normalized if and only if the flag is set (i.e. the 
ModelView matrix is not orthonormal). NAUTO mode is appropriate 
when the model normals are known to be unit length. If nmode is 
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NNORMA, the normal is normalized unconditionally. NNORMA 
mode is appropriate when the model normals may not be unit length. 

NAUTO is the default nmode. 

Because normalization involves division by a computed square root, it 
can adversely affect system performance. 

SEE ALSO 

mmode, loadma, multma, rot, scale, transl, lmbind 

NOTES 

IRIS-4D G, GT, and GTX models, and the Personal Iris, do not support 
nmode. 

nmode cannot be used while draw mode is MSINGL. 

For our purposes a matrix is orthogonal if it transforms normals to the 
same length regardless of their direction, and it is orthonormal if this 
length is the same as the untransformed length. Rotation matrixes are 
always orthonormal. Scale matrixes are orthogonal but not orthonormal 
if the three scale values are identical, neither orthogonal nor orthonor- 
mal otherwise. Uniform scale ModelView matrices can be normalized 
to the identity matrix, and are therefore ignored by the Normal matrix. 
Translations do not affect the upper-left 3x3 ModelView matrix, and are 
therefore also ignored by the Normal matrix. 

The length of a normal is the square root of its dot product with itself. 
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NAME 

nobord - specifies a window without any borders 

FORTRAN 77 SPECIFICATION 
subroutine nobord 

PARAMETERS 

none 

DESCRIPTION 

nobord specifies a window that has no borders around its drawable area. 
Call nobord before you open the window. 

SEE ALSO 

wincon 



c 
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NAME 

noise - filters valuator motion 



FORTRAN 77 SPECIFICATION 

subroutine noise(v, delta) 
integer*4 v, delta 



PARAMETERS 

v expects a valuator. A valuator is a single-value input device. 

delta expects the number of units of change required before the valua- 
tor v can make a new queue entry. 

DESCRIPTION 

noise determines how often queued valuators make entries in the event 
queue. Some valuators are noisy. For example, a device that is not mov- 
ing can still report small fluctuations in value, noise is used to set a 
lower limit on what constitutes a move. That is, the value of a noisy 
valuator v must change by at least delta before the motion is considered 
significant. For example, noise(v,5) means that valuator v must move at 
least 5 units before it makes a new queue entry. 

The default noise value for all valuators is 1, except for the timer dev- 
ices (TIMERn), for which it is 10000. The frequency of timer events is 
returned by the getgde inquiry GDTIME. 

SEE ALSO 

getgde, qdevic, setval 

NOTE 

This routine is available only in immediate mode. 
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NAME 

noport - specifies that a program does not need screen space 

FORTRAN 77 SPECIFICATION 

subroutine noport I 

PARAMETERS 
none 

DESCRIPTION 

noport specifies that a graphics program does not need screen space, 
and therefore does not need a graphics window. This is useful for pro- 
grams that only read or write the color map. Call noport at the begin- 
ning of a graphics program; then call winope to do a graphics initializa- 
tion. 



The system ignores noport if winope is not called. 

SEE ALSO 

winope 

NOTE 

This routine is available only in immediate mode. 



c 
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NAME 

normal - obsolete routine 

FORTRAN 77 SPECIFICATION 

subroutine normal(narray) 
real narray(3) 

PARAMETERS 

narray expects an array containing three floating point numbers. These 
numbers are used to set the value for the current vertex normal. 
Although the declaration specifies a coordinate (real variable), a 
function is called by normal which translates the parameter 
accordingly. 

DESCRIPTION 

This routine is obsolete. Although it continues to function to provide 
backwards compatibility, all new development should use its identical 
replacement, n3f. 

SEE ALSO 

n 
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NAME 

nurbsc - controls the shape of a NURBS trimming curve 

FORTRAN 77 SPECIFICATION 

subroutine nurbsc(knotcount, knotlist, offset, ctlarray, f 

+ order, type) 

integer*4 knotcount, offset 
double precision knotlist(knotcount), ctlarray(*) 
integer*4 order, type 

PARAMETERS 

knotcount expects the number of knots . 

knotlist expects an array of knotcount non-decreasing knot values. 

offset expects the offset (in bytes) between successive curve con- 

trol points 

ctlarray expects an array containing control points for the NURBS 
curve. The coordinates must appear as either (x, y) pairs or 
as (wx, wy, w) triples. The offset between successive con- I 

trol points is given by offset. 

order expects the order of the NURBS curve. The order is one 

more than the degree, hence, a cubic curve has an order 
of 4. 

type expects a value indicating the control point type. Current 

options are NP2D and NP2DR, denoting double-precision 
parametric coordinates in the two-dimensional parameter 
space of a trimmed surface. NP2D denotes non-rational (2) 
coordinates, while NP2DR denotes rational (3) coordinates. 

DESCRIPTION 

Use nurbsc to describe a NURBS curve. Use NURBS curves within 
trimming loop definitions. A trimming loop definition is a set of ^ 
oriented curve commands that describe a closed loop. To mark the f 
beginning of a trimming loop definition, use the bgntri command. To 
mark the end of a trimming loop definition, use an endtri command. 
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You use trimming loop definitions within NURBS surface definitions 
(see bgnsur). The trimming loops are closed curves that the system uses 
to set the boundaries of a NURBS surface. You can describe a trimming 
loop by using a series of NURBS curves, piecewise linear curves (see 
pwlcur), or both. 

When the system needs to decide which part of a NURBS surface you 
want it to display, it displays the region of the NURBS surface that is to 
the left of the trimming curves as the parameter increases. Thus, for a 
counter-clockwise oriented trimming curve, the displayed region of the 
NURBS surface is the region inside the curve. For a clockwise oriented 
trimming curve, the displayed region of the NURBS surface is the 
region outside the curve. 

The offset parameter is used in case the control points are part of an 
array of larger structure elements. The nurbscurve routine searches for 
the tt-th control point pair or triple beginning at byte address 
ctlarray + «x offset. 

See the Graphics Library Programming Guide for a mathematical 
description of a NURBS curve. 

SEE ALSO 

bgnsur, nurbss, bgntri, pwlcur, setnur, getnur 
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NAME 

nurbss - controls the shape of a NURBS surface 

FORTRAN 77 SPECIFICATION 

subroutine nurbss(sknotcount, sjknot, tknotcount, tknot, 
+ soffset, toffset, ctlarray, sorder, torder, type) 

integer*4 sknotcount, tknotcount 
double precision sknot(sknotcount), tknot(tknotcount) 
integer*4 soffset, toffset 
double precision ctlarray(*) 
integer*4 sorder, torder, type 



PARAMETERS 

sknotcount 

sknot 

tknotcount 
tknot 

soffset 

toffset 

ctlarray 



sorder 



expects the number of knots in the parametric s direc- 
tion. 

expects an array of sknotcount non-decreasing knot 
values in the parametric s direction. 

expects the number of knots in the parametric t direction. 

expects an array of tknotcount non-decreasing knot 
values in the parametric t direction. 

expects the offset (in bytes) between successive control 
points in the parametric s direction in ctlarray. 

expects the offset (in bytes) between successive control 
points in the parametric t direction in ctlarray. 

expects an array containing control points for the 
NURBS surface. The coordinates must appear as either 
(x,y,z) triples or as (wx f wy,wz,w) quadruples. The 
offsets between successive control points in the 
parametric s and t directions are given by soffset and 
toffset 

expects the order of the NURBS surface in the 
parametric s direction. The order is one more than the 
degree, hence, a cubic surface has an order of 4. 



c 



c 



Version 3.0 



■1 - 



April 1990 



nurbss Graphics Reference, FORTRAN nurbss 



torder expects the order of the NURBS surface in the 

parametric t direction. The order is one more than the 
degree, hence, a cubic surface has an order of 4. 

type expects a value indicating the control point type. 

Current options are NV3D, NV3DR, NC4D, NC4DR, 
and NT2D, NT2DR. Types NV3D and NV3DR denote 
double-precision positional coordinates in a three- 
dimensional model space. NV3D denotes non-rational 
(3) coordinates and NV3DR denotes rational (4) coordi- 
nates. Types NC4D and NC4DR denote double- 
precision color coordinates in a four-dimensional RGBA 
color space. NC4D denotes non-rational coordinates and 
NC4DR denotes rational coordinates. Types NT2D and 
NT2DR denote double-precision texture coordinates in a 
two-dimensional texture space. NT2D denotes non- 
rational coordinates and NT2DR denotes rational coordi- 
nates. 

DESCRIPTION 

Use the nurbss command within a NURBS (Non-Uniform Rational B- 
Spline) surface definition to describe the shape of a NURBS surface 
before any trimming takes place. To mark the beginning of a NURBS 
surface definition, use the bgnsur command. To mark the end of a 
NURBS surface definition, use the endsur command. Call nurbss 
within a NURBS surface definition only. 

Positional, texture, and color coordinates are associated by presenting 
each as a separate nurbss between a bgnsur/endsurf pair. No more 
than one call to nurbss for each of color and texture data may be made 
within a single bgnsur/endsurf pair. Exactly one call must be made to 
describe position data and it must be the last call to nurbss between the 
bracketing bgnsur/endsurf. 

EXAMPLE 
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call bgnsur 






call nurbss ( . 


. . , N_C4D 


) 


call nurbss ( . 


. . , N_T2D 


) 


call nurbss ( . 


. . , N_V3D 


) 


call endsur 







You can trim a NURBS surface by using the commands nurbsc and 
pwlcur between calls to bgntri and endtri. 

Observe that a nurbss with sknotcount knots in the s direction and 
tknotcount knots in the t direction with orders sorder and torder must 
have {sknotcount - sorder) x (tknotcount - torder) control points. 

The system renders a NURBS surface as a polygonal mesh and analyti- 
cally calculates normal vectors at the corners of the polygons within the 
mesh. Therefore, your code should specify a lighting model when it 
uses NURBS surfaces. Otherwise, you loose all the interesting surface 
information. Use Imdef and lmbind to define or modify materials and 
their properties. 

See the Graphics Library Programming Guide for a mathematical 
description of a NURBS surface. 

SEE ALSO 

bgnsur, nurbsc, bgntri, pwlcur, setnur, getnur, texbin 



NOTE 



nurbss commands specifying color or texture coordinates currently 
have no effect on IRIS-4D G, GT, GTX, and Personal IRIS. 



( 
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NAME 

objdel - deletes routines from an object 

FORTRAN 77 SPECIFICATION 

subroutine objdel(tagl, tag2) 
integer*4 tagl, tag2 

PARAMETERS 

tagl expects the tag indicating where the deletion is to be started from. 
tag! expects the tag indicating where the deletion should stop. 

DESCRIPTION 

objdel is an object editing routine. It deletes the routines as well as any 
tags starting immediately after tagl and ending just prior to tag2. tagl 
and tag2 remain in the text. 

If no object is open for editing (see editob) when objdel is called, it is 
ignored. 

objdel leaves the pointer at the end of the object after it executes. 

SEE ALSO 

editob, objins, objrep 

NOTE 

This routine is available only in immediate mode. 
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NAME 

objins - inserts routines in an object at a specified location 

FORTRAN 77 SPECIFICATION 

subroutine objins(t) i 

integer*4 1 

PARAMETERS 

t expects a tag within the object definition that is to be edited. 

DESCRIPTION 

objins positions an editing pointer on the routine specified by t. The 
additional graphics routines should now be inserted after the tag. 

Use closeo (objdel, objins, or objrep) to terminate the insertion. 



SEE ALSO 

closeo, editob, maketa, objdel, objrep 

NOTE 

This routine is available only in immediate mode. 



c 



( 
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NAME 

objrep - overwrites existing display list routines with new ones 

FORTRAN 77 SPECIFICATION 

subroutine objrep(t) 
integer*4 1 

PARAMETERS 

t expects a tag within the object definition that is to be edited. 

DESCRIPTION 

objrep combines the functions of objins and objdel. Graphics routines 
that follow objrep overwrite existing ones until closeo, objins, objdel, 
or objrep terminates the replacement. This replacement begins with the 
line immediately following the tag specified by t. 

objrep requires that the new routine be the same length as the one it 
replaces; this makes replacement operations fast. Use objdel and objins 
for more general replacement. 

Use objrep as a quick method to create a new version of a routine. 

SEE ALSO 

closeo, editob, objdel, objins 

NOTE 

This routine is available only in immediate mode. 
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NAME 

onemap - organizes the color map as one large map 

FORTRAN 77 SPECIFICATION 
subroutine onemap 

PARAMETERS 

none 

DESCRIPTION 

onemap organizes the color map of the currently active framebuffer as a 
single map. Because single map mode is the default value for all GL 
framebuffers, it can be called in any of the framebuffer drawmodes 
(NORMAL, PUPDRA, OVERDR, and UNDERD). To return the nor- 
mal framebuffer to single map mode, however, you must call onemap 
while in drawmode NORMAL. 

The single color map allocated to a framebuffer in onemap mode has as 
many entries as are supported by the bitplanes in that framebuffer. The 
normal framebuffer has up to 12 bitplanes, and therefore up to 4096 
color map entries. Call getpla after setting draw mode to the desired 
framebuffer to determine the color map size, getgde can also be called 
at any time to determine the size of the color map of any framebuffer. 

onemap does not take effect until gconfi is called. When called, gconfi 
executes onemap requests pending for all draw modes, regardless of the 
current draw mode. 

A framebuffer 9 s color map is used to display pixels only if the frame- 
buffer is in color map mode (see cmode). 

SEE ALSO 

cmode, drawmo, gconfi, getcmm, getmap, multim, setmap 

NOTE 

This routine is available only in immediate mode. 



c 



( 



( 
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NAME 

ortho, ortho2 - define an orthographic projection transformation 

FORTRAN 77 SPECIFICATION 

subroutine ortho(left, right, bottom, top, near, far) 
real left, right, bottom, top, near, far 

subroutine ortho2(left, right, bottom, top) 
real left, right, bottom, top 

The above routines are functionally the same. They differ only in that 
ortho is used for 3-D applications and ortho2 is used for 2-D applica- 
tions. 

PARAMETERS 

left expects the coordinate for the left vertical clipping plane. 

right expects the coordinate for the right vertical clipping plane. 

bottom expects the coordinate for the bottom horizontal clipping plane. 

top expects the coordinate for the top horizontal clipping plane. 

near expects the distance to the nearer depth clipping plane. 

far expects the distance to the farther depth clipping plane. 

DESCRIPTION 

ortho specifies a box-shaped enclosure in the eye coordinate system that 
is mapped to the viewport, left, right, bottom, top, near, mdfar specify 
the location of the x, y, and z clipping planes, near and far are distances 
along the line of sight from the eye space origin; the z clipping planes 
are at -near and -far. 

ortho2 is the 2-D version of ortho, and specifies a rectangle that is the 
mapped to the viewport. When you use ortho2 with 3-D world coordi- 
nates, the z coordinates are not transformed and will be clipped if they 
lie outside the range -1 < z < 1. 
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When the system is in single matrix mode, both ortho and ortho2 load a 
matrix onto the matrix stack, thus replacing the current top matrix. 
When the system is in viewing, projection, or texture matrix mode, the 
system replace the current Projection matrix without changing the 
ModelView matrix stack or the Texture matrix. 

GL window coordinates have integer values at the centers of pixels. 
Thus to correctly specify a one-to-one orthographic mapping from eye- 
coordinates to window-coordinates, the edges of the viewable volume 
should be set to 1/2-pixel values. For example, the 1280 x 1024 full 
screen is correctly mapped one-to-one from eye-coordinates to 
window-coordinates by the commands: 

ortho2 (-0.5, 1279.5,-0.5, 1023.5) 
viewpo (0, 1279, 0, 1023) 

Note that ortho, unlike perspe and window, allows the viewpoint to be 
moved from the origin of the coordinate system. Thus ortho combines 
a trivial viewing transformation (translation from the origin) with its 
projection operation. Be sure not to duplicate the orthographic transla- 
tion in your viewing transformation. 

SEE ALSO 

mmode, perspe, viewpo, window 



c 



c 



( 
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NAME 

overla - allocates bitplanes for display of overlay colors 

FORTRAN 77 SPECIFICATION 

subroutine overla(planes) 
integer*4 planes 

PARAMETERS 

planes expects the number of bitplanes to be allocated for overlay 
colors. Valid values are 0, 2 (the default), 4, and 8. 

DESCRIPTION 

The IRIS physical framebuffer is divided into four separate GL frame- 
buffers: normal, popup, overlay, underlay. Because a single physical 
framebuffer is used to implement the four GL framebuffers, bitplanes 
must be allocated among the GL framebuffers. overla specifies the 
number of bitplanes to be allocated to the overlay framebuffer. overla 
does not take effect immediately. Rather, it is considered only when 
gconfi is called, at which time all requests for bitplane resources are 
resolved. 

While only one of the four GL framebuffers can be drawn to at a time 
(see drawmo), all four are displayed simultaneously. The decision of 
which to display at each pixel is made based on the contents of the four 
framebuffers at that pixel location, using the following hierarchical rule: 

if the popup pixel contents are non-zero 

then display the popup bitplanes 

else if overlay bitplanes are allocated AND 
the overlay pixel contents are non-zero 

then display the overlay bitplanes 

else if the normal pixel contents are non-zero OR 
no underlay bitplanes are allocated 
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NAME 

pageco - sets the color of the textport background 

FORTRAN 77 SPECIFICATION 

subroutine pageco(pcolor) I 

integer*4 pcolor 

PARAMETERS 

pcolor expects an index into the current color map. 

DESCRIPTION 

pageco sets the background color of the textport of the calling process. 
If the calling process was invoked from a wsh window, this window is 
used for its textport; otherwise, the process does not have a textport and 
this routine does nothing. 

SEE ALSO 

textco I 

wsh(l) in the User' s Reference Manual 

NOTES 

This routine is available only in immediate mode. 

A process launched from 4Sight or The IRIS Workspace™ will not have 
a textport. Therefore, we do not recommend the use of this routine in 
new development. 



c 
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NAME 

passth - passes a single token through the Geometry Pipeline 

FORTRAN 77 SPECIFICATION 

subroutine passth(token) 
integer*4 token 

PARAMETERS 

token expects an integer which is used to mark specific sections in 
input data so that when it is returned from the feedback buffer 
the data is easier to decipher. 

DESCRIPTION 

passth passes a single 16-bit integer through the Geometry Pipeline. 
Use it in feedback mode to parse the returned information. 

For example, you can use passth between every pair of points that is 
being transformed and clipped by the Geometry Engines. If a point is 
clipped out, two passth tokens appear in a row in the output buffer. 

NOTE 

This routine is available only in feedback mode; otherwise it is ignored. 
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NAME 

patch - draws a surface patch 

FORTRAN 77 SPECIFICATION 

subroutine patch(geomx, geomy, geomz) 
real geomx(4,4), geomy(4,4), geomz(4,4) 

PARAMETERS 

geomx expects the 4x4 matrix which contains the x coordinates of the 
16 control points of the patch. 

geomy expects the 4x4 matrix which contains the y coordinates of the 
16 control points of the patch. 

geomz expects the 4x4 matrix which contains the z coordinates of the 
16 control points of the patch. 

DESCRIPTION 

patch draws a surface patch using the current patchb, patchp, and 
patchc which are defined earlier. The control points geomx, geomy, 
geomz determine the shape of the patch. 

The patch is drawn as a web of curve segments. Each curve segment is 
approximated by a sequence of straight lines. All lines use the current 
linestyle, which is reset prior to the first line of each curve segment, and 
continues through subsequent lines in each curve segment. Other line 
modes, including depthcueing, line width, and line antialiasing, also 
apply to the lines generated by patch. 

SEE ALSO 

defbas, patchb, patchc, patchp, rpatch 



c 
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NAME 

patchb - sets current basis matrices 

FORTRAN 77 SPECIFICATION 

subroutine patchh(uid, vid) 
integer*4 uid, vid 

PARAMETERS 

uid expects the basis that defines how the control points determine the 
shape of the patch in the "u" direction. 

vid expects the basis that defines how the control points determine the 
shape of the patch in the "v" direction. 

DESCRIPTION 

patchb sets the current basis matrices (defined by defbas) for the u and 
v parametric directions of a surface patch, patch uses the current u and 
v bases when it executes. 

SEE ALSO 

defbas, patch, patchp, patchc, rpatch 
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NAME 

patchc - sets the number of curves used to represent a patch 

FORTRAN 77 SPECIFICATION 

subroutine patchc(ucurves, vcurves) | 

integer*4 ucurves, vcurves ^ 

PARAMETERS 

ucurves expects the number of curve segments that will be drawn in 
the V direction. 

vcurves expects the number of curve segments that will be drawn in 
the "v" direction. 

DESCRIPTION 

patchc sets the number of u and v curves in the wire frame that 
represents a patch. 



SEE ALSO 

patch, patchb, patchp, rpatch 



( 



c 
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NAME 

patchp - sets the precision at which curves are drawn in a patch 

FORTRAN 77 SPECIFICATION 

subroutine patchp(usegs, vsegs) 
integer*4 usegs, vsegs 

PARAMETERS 

usegs expects the number of line segments used to draw a curve in the 
"u" direction. 

vsegs expects the number of line segments used to draw a curve in the 
"v" direction. 

DESCRIPTION 

patchp sets the precision with which the system draws the curves that 
make up a wireframe patch. Patch precisions are similar to curve preci- 
sions. 

SEE ALSO 

curvep, patchb, patchc, patch, rpatch 
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NAME 

pclos - closes a filled polygon 

FORTRAN 77 SPECIFICATION 

subroutine pclos I 

PARAMETERS 

none 

DESCRIPTION 

pclos closes a filled polygon that has been created by using pmv and a 
sequence of pdr calls (or rpmv and rpdr calls). It is not needed when 
using poly or polf because these procedures close the polygon within 
their own routines, pclos closes the polygon by connecting the last 
point with the first. The polygon so defined is filled using the current 
pattern, color, and writemask. For example, the following sequence 
draws a filled square: 



call 


pmv ( . , 


0. 


.0, 


0. 


.0) 


call 


pdr (1.0, 


0, 


.0, 


0. 


.0) 


call 


pdr (1 .0, 


1. 


.0, 


0. 


.0) 


call 


pdr (0.0, 


1. 


.0, 


0. 


.0) 


call 


pclos 










SEE ALSO 












bgnpol, endpol, pdr, 


pmv, 


V 





( 



NOTES 



pclos should not be used in new development. Rather, polygons should 
be drawn using the high-performance v commands, surrounded by calls 
to bgnpol and endpol. 

There can be no more than 256 vertices in a polygon. Therefore, there 

can be no more than 255 pdr calls between pmv and pclos. £ 
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Be careful not to confuse pclos with the IRIX system call pclose, which 
closes an IRIX pipe. 
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NAME 

pdr, pdri, pdrs, pdr2, pdr2i, pdr2s - specifies the next point of a 
polygon 

FORTRAN 77 SPECIFICATION f 

subroutine pdr(x, y, z) ^ 

real x, y, z 

subroutine pdri(x, y, z) 
integer*4 x, y, z 

subroutine pdrs(x ? y, z) 
integer*2 x, y, z 

subroutine pdr2(x, y) 
real x, y 

subroutine pdr2i(x, y) 
integer*4 x, y 

subroutine pdr2s(x, y) 
integer*2 x, y 

All of the above routines are functionally the same. They differ only in I 

the type declarations of their parameters and in whether they expect a 
two- or three-dimensional space. 

PARAMETERS 

x expects the x coordinate of the next defining point for the polygon. 
y expects the y coordinate of the next defining point for the polygon, 
z expects the z coordinate of the next defining point for the polygon. 

DESCRIPTION 

pdr specifies the next point of a polygon. When pdr is executed, it 
draws a line to the specified point Qc,y,z) which then becomes the current 
graphics position. The next pdr call will start drawing from that point. - 

To draw a typical polygon start with pmv, follow it with a sequence of I 
calls to pdr and end it with pclos. 
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EXAMPLE 

The following sequence draws a square: 

call pmv(0.0, 0.0, 0.0) 

call pdr (1.0, 0.0, 0.0) 

call pdr(1.0, 1.0, 0.0) 

call pdr(0.0, 1.0, 0.0) 
call pclos 

SEE ALSO 

bgnpol, endpol, pclos, pmv, v 

NOTES 

pdr should not be used in new development. Rather, polygons should 
be drawn using the high-performance v commands, surrounded by calls 
to bgnpol and endpol. 

There can be no more than 256 vertices in a polygon. Therefore, there 
can be no more than 255 pdr calls between pmv and pclos. 
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NAME 

perspe - defines a perspective projection transformation 

FORTRAN SPECIFICATION 

subroutine perspe(fovy, aspect, near, far) | 

integer*4 fovy ^ 

real aspect, near, far 

PARAMETERS 

fovy expects the field-of~view angle in the y direction. The field of 
view is the range of the area that is being viewed, fovy must be 
> 2 or an error results. 

aspect expects the aspect ratio which determines the field of view in 
the x direction. The aspect ratio is the ratio of x (width) to y 
(height). 

near expects the distance from the viewer to the closest clipping 
plane (always positive). 

far expects the distance from the viewer to the farthest clipping f 
plane (always positive). ^ 

DESCRIPTION 

perspe specifies a viewing pyramid into the world coordinate system. 
In general, the aspect ratio in perspe should match the aspect ratio of 
the associated viewport. For example, aspect=2.0 means the viewer's 
angle of view is twice as wide in x as it is in y. If the viewport is twice 
as wide as it is tall, it displays the image without distortion. 

When the system is in single matrix mode, perspe loads a matrix onto 
the transformation stack, replacing the current top matrix. When the 
system is in viewing, projection, or texture matrix mode, perspe 
replaces the current Projection matrix and leaves the ModelView matrix 
stack and the Texture matrix unchanged. 



c 
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SEE ALSO 

mmode, ortho, viewpo, window 
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NAME 

pick - puts the system in picking mode 

FORTRAN 77 SPECIFICATION 

subroutine pick(buffer, numnam) I 

integer*2 buffer(*) 
integer*4 numnam 

PARAMETERS 

buffer expects the array to use for storing names. 

numnam expects the maximum number of names to store. 

DESCRIPTION 

pick facilitates the cursor as a pointing object. When you draw an 
image in picking mode, nothing is drawn. It places a special viewing 
matrix on the stack, which discards everything in the image that does 
not intersect a small region around the cursor origin. 

The graphical items that intersect the picking region are hits and store \ 
the contents of the name stack in buffer. Picking does not work if you 
issue a new viewport in picking mode. 

SEE ALSO 

endpic, endsel, gselec, picksi, pushna, popnam, loadna 

NOTE 

This routine is available only in immediate mode. 



c 
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NAME 

picksi - sets the dimensions of the picking region 

FORTRAN 77 SPECIFICATION 

subroutine picksi(deltax, deltay) 
integer*4 deltax, deltay 

PARAMETERS 

deltax expects the new width of the picking region. 
deltay expects the new height of the picking region. 

DESCRIPTION 

picksi changes the dimensions of the picking region. The default setting 
is 10 pixels. The picking region is rectangular and is centered at the 
current cursor position, the origin of the cursor glyph. In picking mode, 
any objects that intersect the picking region are reported in the picking 
buffer. 

SEE ALSO 

pick 

NOTE 

This routine is available only in immediate mode. 
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NAME 

pixmod - specify pixel transfer mode parameters 

FORTRAN SPECIFICATION 

subroutine pixmod(mode, value) | 

integer*4 mode, value ^ 

PARAMETERS 

mode One of the symbolic constants: 

(parameters that affect read, write, and copy transfers) 

PMSHIF, default value: 0. Number of bit positions that pixel 
data are to be shifted. Positive shifts are left for write and copy, 
right for read. Valid values: 0, +-1, +-4, +-8, +-12, +-16, +-24 

PMEXPA, default value: 0. Enable (1) or disable (0) expansion 
of single-bit pixel data to one of two 32-bit pixel values. Valid 
values: 0, 1 

PMC0, default value: 0. Expansion value (32-bit packed color) 
chosen when the single-bit pixel being expanded is zero. Valid 
values: any 32-bit value 

PMC1, default value: 0. Expansion value (32-bit packed color) 
chosen when the single-bit pixel being expanded is one. Valid 
values: any 32-bit value 

PMADD2, default value: 0. Amount to be added to the least- 
significant 24 bits of the pixel (signed value). Valid values: a 
32-bit signed value in the range -0x800000 through OxTfffff 

Although this value is specified as a 32-bit integer, the sign bit 
MUST be smeared across all 32 bits. Thus -0x800000 specifies 
the minimum value; and 0x800000 is out of range at the positive 
end. 



PMTTOB, default value: 0. Specifies that fill (for write and 
copy transfers) and read (for read transfers) must be top-to- 
bottom (1) or bottom-to-top (0). Valid values: 0, 1 



c 



c 
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PMRTOL, default value: 0. Specifies that fill (for write and 
copy transfers) and read (for read transfers) is to be right-to-left 
(1) or left-to-right (0). Valid values: 0, 1 

PMSIZE, default value: 32. Number of bits per pixel. Used for 
packing during reads and writes. Used to optimize internal 
transfers during copies. Valid values: 1, 4, 8, 12, 16, 24, 32 

Although size specification is for the entire pixel, there is no 
mechanism for specifying reduced RGBA component sizes (such 
as 12-bit RGB with 4 bits per component). 

(parameters that affect read and write transfers only) 

PMOFFS, default value: 0. Number of bits of the first CPU 
word of each scanline that are to be ignored. Valid values: 
through 31 

PMSTRI, default value: 0. Number of 32-bit CPU words per 
scanline in the original image (not just the portion that is being 
transferred by this command). Valid values: any non-negative 
integer 

(parameters that affect write and copy transfers only) 

PMZDAT, default value: 0. Indicates (1) that pixel data are to 
be treated as Z data rather than color data (0). Destination is the 
Z-buffer. Writes are conditional if zbuffering is on. Valid 
values: 0, 1 

value Integer value assigned to mode. 

DESCRIPTION 

pixmod allows a variety of pixel transfer options to be selected. These 
options are available only for pixel transfer commands that operate on 
32-bit data: lrectr, lrectw, and rectco. Pixel transfer commands that 
operate on 8-bit data (readRG, writeR) and on 16-bit data (readpi, 
writep, rectre, rectwr) do not support pixmod capabilities. Note that 
lrectr, lrectw, and rectco are valid in both color map and RGB modes. 

Padding in CPU Memory 
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Transfer commands Irectr and Irectw operate on pixel data structures in 
CPU memory. These data structures contain data organized in row- 
major format, each row corresponding to one scanline of pixel data. 
Adjacent pixels are packed next to each other with no padding, regard- 
less of the pixel size. Thus in many cases pixels straddle the 32-bit 
word boundaries. It is always the case, however, that each scan line 
comprises an integer number of whole 32-bit words. If the pixel data do 
not exactly fill these words, the last word is padded with (undefined) 
data. 

Addresses passed to Irectr and Irectw must be long word aligned. If 
not, an error message is generated and no action is taken. 

Packing in CPU Memory 

Transfer commands Irectr and Irectw operate on pixel data that are 
packed tightly into CPU memory. Adjacent pixels, regardless of their 
size, are stored with no bit padding between them. Pixel size, and thus 
packing, is specified by PMSIZE. The default value of this parameter 
is 32, meaning that 32-bit pixels are packed into 32-bit CPU memory 
words. 

Although the MIPS processor is a big-endian machine, its bit numbering 
is little-endian. Pixel data are packed consistent with the byte number- 
ing scheme (big-endian), ignoring the bit numbering. Thus, 12-bit 
packed pixels are taken as follows (by Irectw) from the first 32-bit word 
of a CPU data structure: 



c 
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first CPU word 

byte number 12 3 

bit number 33222222 22221111 111111 

10987654 32109876 54321098 76543210 

first unpacked pixel 11 

10987654 3210 
second unpacked pixel 11 

1098 76543210 
third unpacked pixel 11 

10987654 ... 

When being written, unpacked pixels are padded to the left with zeros to 
make their size equal to the size of the framebuffer target region (12 bits 
total in color map mode, 24 bits total when writing Z values, 32 bits 
total in RGB mode). The least significant bit of the unpacked pixel 
becomes the least significant bit of the framebuffer pixel it replaces. 

Note that big-endian packing makes 8 and 16 bit packing equivalent to 
integer* 1 and integer*2 arrays. Remember, however, that the address 
passed to lrectw or lrectr must be long- word aligned. 

Packings of 1, 4, 8, 12, 16, 24, and 32 bits per pixel are supported. Set- 
ting PMSIZE to a value other than one of these results in an error mes- 
sage, and leaves the current size unchanged. 

Order of Pixel Operations 

In addition to packing and unpacking, pixel streams are operated on in a 
variety of other ways. These operations occur in a consistent order, 
regardless of whether the stream is being written, read, or copied. 

write unpack->shift->expand->add24->zoom->fbpack 
copy format->shift->expand->add24->zoom->fbpack 
read format->shift->expand->add24 ->pack 

Note that pixel data are unpacked only when being transferred from 
CPU memory to the framebuffer, and that they are unpacked prior to 
any other operation. Likewise, pixel data are packed only when being 
transferred to CPU memory. Packing occurs after all other operations 
have been completed. Because copy operations neither pack nor unpack 
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pixel data, the rectcopy command ignores the value of PMSIZE, 

Framebuffer Format 

Each IRIS framebuffer is always configured in one of two fundamental 
ways: color map or RGB. In die RGB configuration 3 or 4 color com- 
ponents (red, green, blue, and optionally alpha) are stored at each pixel f 
location. Each component is stored with a maximum of 8 bits of preci- 
sion, resulting in a packed 32-bit pixel with the following format: 

33222222 22221111 111111 

10987654 32109876 54321098 76543210 

aaaaaaaa bbbbbbbb gggggggg rrrrrrrr 
76543210 76543210 76543210 76543210 



Some IRIS framebuffers store fewer than 8 bits per color component 
while in RGB mode. These framebuffers, however, emulate all the 
behavior of full 32-bit framebuffers. Thus the first operation in both the 
copy and read streams (above) is format: converting the framebuffer- 
format data to the 8-bit per component RGBA format that all subsequent 
operations execute with. Likewise, the final operation in both the write 
and copy streams (above) is fbpack: converting the 8-bit per component 
RGBA data back to the hardware-specific storage format. Both the for- 
mat and the fbpack operation are null operations if the hardware sup- 
ports full 32-bit RGBA data. 



In its color map configuration a single color index, from 1 to 12 bits, is 
stored at each pixel location: 



33222222 22221111 111111 

10987654 32109876 54321098 76543210 

iiii iiiiiiii 

11 

1098 76543210 



Pixel Shifting 



c 
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Pixels taken from the framebuffer (Irectr, rectco) or unpacked from 
CPU memory (lrectw) are first rotated either left or right by an amount 
up to 24 bit positions. Unpacked pixels and pixel values to be packed 
are padded left and right by zeros during the shift operation. The result- 
ing 32-bit pixel values therefore include ones only in the region that was 
filled with legitimate pre-shifted data. Copied pixels may not be padded 
with zeros; thus a writemask may be required to eliminate unwanted 
bits. 

Pixel shifting is enabled by setting PMSHIF to a non-zero value. Posi- 
tive values in the range 1-24 specify left shifts while writing or copying, 
right shifts while reading. Negative values in the range -1 through -24 
specify right shifts while writing or copying, left shifts while reading. 

The default shift value is zero (i.e. shifting disabled). Other accepted 
values are plus and minus 1, 4, 8, 12, 16, and 24. 

Because pixels are always converted to the formats described above 
before they are shifted, shift operations are largely independent of the 
hardware framebuffer storage format. 

Pixel Expansion 

Single bit pixels can be expanded to one of two full 32-bit color values, 
based on their binary value. This expansion is enabled by setting 
PMEXPA to 1 (the default disabled value is 0). When expansion is 
enabled, zero value pixels are replaced by the packed color PMCO, and 
one value pixels are replaced by PMC1. Bits 11-0 of PMCO and PMC1 
specify color index values when in color map mode. 

Pixel expansion is actually controlled by bit zero of the incoming pixel 
(regardless of the size of the incoming pixel). Because pixel shifting 
preceeds pixel expansion, any bit of the incoming pixel can be selected 
to control pixel expansion. 

There are no constraints on the values of PMCO or PMC1. 

Pixel Addition 

The pixel addition stage treats the lower 24 bits of each incoming pixel 
as a signed integer value. It adds a signed 24-bit constant to this field 
of the pixel, leaving the upper 8 bits unchanged. The result of the addi- 
tion is clamped to the range -2 through 2-1. While this addition is 
most useful when writing or copying depth data, it is enabled during all 
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transfers. Thus PMADD2 is typically changed from its default zero 
value only while depth transfers are being done (See "Drawing Z Data" 
below). Pixel addition can also be used to offset the range of a color 
map image. 

Rectangle within Rectangle in CPU Memory 

Variables PMOFFS and PMSTRI support transfer operation on rec- 
tangular pixels regions that reside within larger regions in CPU 
memory. PMOFFS, set to a value in the range 0-31, specifies the 
number of significant bits of the first CPU word that are ignored at the 
start of each scanline transfer. For example, an Irectw transfer of 12-bit 
packed pixel data with PMOFFS set to 12 results in the following pixel 
extraction: 

first CPU word of each scanline 

byte number 12 3 

bit number 33222222 22221111 111111 

10987654 32109876 54321098 76543210 

first unpacked pixel 11 

1098 76543210 
second unpacked pixel 11 

10987654 . . . 

Pixel unpacking continues tightly throughout all the CPU words that 
define a single scanline. After the last CPU word that defines a scanline 
has been transferred, the CPU read pointer is advanced to the 32-bit 
word at location (first PMSTRI). PMOFFS pixels of this word are 
skipped, then this scanline is transferred to the graphics engine. The 
PMSTRI value of zero is exceptional, causing the CPU read pointer to 
be advanced to the 32-bit word that immediately follows the last word 
of each scanline. 

PMOFFS and PMSTRI, like PMSIZE, are ignored by framebuffer-to- 
framebuffer transfers (rectco). They both default to a value of zero. 

Alternate Fill Directions 



( 



c 



c 



Version 3.0 - 7 - April 1 990 



pixmod Graphics Reference, FORTRAN pixmod 



During read, copy, and write pixel operations pixels are always 
transferred in row-major order. By default scanlines are read or written 
left-to-right, starting with the bottom scanline and working up. Parame- 
ters PMRTOL and PMTTOB allow the horizontal and vertical read/fill 
directions to be reversed, but do not change the fundamental row-major 
scan order. PMRTOL specifies right-to-left traversal/fill when set to 
one, left-to-right when set to its default value of zero. PMTTOB 
specifies top-to-bottom traversal/fill when set to one, bottom-to-top 
when set to its default value of zero. 

These parameters can be used to properly deal with CPU data formats 
that differ from the default IRIS pixel order. They also can be used to 
generate image reflections about either the X or Y screen axes, (see 
notes.) 

Fill direction does not affect the location of the destination rectangle 
(i.e. the destination rectangle is always specified by its lower-left pixel, 
regardless of its traversal/fill direction). 

Drawing Z Data 

Normally pixel data are treated as colors. Zbuffer mode must be false 
during Irectw and rectco of color values, because there are no source Z 
values to do the buffer compares with. Setting PMZDAT to 1.0, how- 
ever, instructs the GL to treat incoming pixel values as Z values, and to 
treat source color as undefined. When drawing pixels with PMZDAT 
enabled, the system automatically insures that no changes are made to 
color bitplanes, regardless of the current color write mask. When 
PMZDAT and zbuffe are both enabled, pixel values will be condition- 
ally written into the z-buffer in the usual manner, and the color buffer 
will be unaffected. 

Z-buffered images are drawn by doing two transfers, first of the Z values 
(with PMZDAT enabled and stencil set based on the outcome of the Z 
comparison) and then of the color values (with PMZDAT disabled, 
drawn conditionally based on the stencil value). 

It is not necessary (or correct) to enable zdraw mode while doing pixel 
transfers with PMZDAT enabled. 
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SEE ALSO 

lrectr, Irectw, rectco, rectzo, stenci 

NOTES 

IRIS-4D G, GT, and GTX models, and the Personal Iris, do not support 
pixmod. 
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NAME 

pmv, pmvi, pmvs, pmv2, pmv2i, pmv2s - specifies the first point of a 
polygon 

FORTRAN 77 SPECIFICATION 

subroutine pmv(x, y, z) 
real x, y, z 

subroutine pmvi(x, y, z) 
integer*4 x, y, z 

subroutine pmvs(x, y, z) 
integer*2 x, y, z 

subroutine pmv2(x, y) 
real x, y 

subroutine pmv2i(x, y) 
integer*4 x, y 

subroutine pmv2s(x, y) 
integer*2 x, y 

All of the above routines are functionally the same. They differ only in 
the type declarations of their parameters and in whether or not they 
assume a two-dimensional or three-dimensional space. 

PARAMETERS 

x expects the x coordinate of the first point if a polygon. 
y expects the y coordinate of the first point of a polygon. 
z expects the z coordinate of the first point of a polygon. 

DESCRIPTION 

pmv specifies the starting point of a polygon. The next drawing com- 
mand will start drawing from this point. You draw a typical polygon 
with a pmv, a sequence of pdr, and close it with a pclos. 
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Between pmv and pclos, you can only issue the following Graphics 
Library subroutines: c, color, RGBcol, cpack, Imdef, Imbind n, pdr, 
and v. Only use Imdef and Imbind to respecify materials and their pro- 
perties. 

EXAMPLE (^ 

The following sequence draws a square: 



call 


pmv ( . , 





.0, 


0. 


0) 


call 


pdr (1.0, 





.0, 


0. 


.0) 


call 


pdr (1.0, 


1 


.0, 


0. 


.0) 


call 


pdr (0.0, 


1 


.0, 


0. 


.0) 


call 


pclos 










SEE ALSO 












bgnpol, endpol, pclos, 


pdr 


,v 





NOTES 



pmv should not be used in new development. Rather, polygons should 

be drawn using the high-performance v commands, surrounded by calls | 

to bgnpol and endpol. V 

There can be no more than 256 vertices in a polygon. Therefore, there 
can be no more than 255 pdr calls between pmv and pclos. 



( 
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NAME 

pnt, pnti, pnts, pnt2, pnt2i, pnt2s - draws a point 

FORTRAN 77 SPECIFICATION 

subroutine pnt(x, y, z) 
real x, y, z 

subroutine pnti(x, y, z) 
integer*4 x, y, z 

subroutine pnts(x, y, z) 
integer*2 x, y, z 

subroutine pnt2(x, y) 
real x, y 

subroutine pnt2i(x, y) 
integer*4 x, y 

subroutine pnt2s(x, y) 
integer*2 x, y 

All of the above routines are functionally the same. They differ only in 
the type declarations of their parameters and in whether or not they 
assume a two-dimensional or three-dimensional space. 

PARAMETERS 

x expects the x coordinate of the point to be drawn. 
y expects the y coordinate of the point to be drawn. 
z expects the z coordinate of the point to be drawn. 

DESCRIPTION 

pnt colors a point in world coordinates. If the point is visible in the 
current viewport, it is shown as one pixel. The pixel is drawn in the 
current color (if in depth-cue mode, the depth-cued color is used) using 
the current writemask. pnt updates the current graphics position after it 
executes. A drawing routine immediately following pnt will start draw- 
ing from the point specified. 
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SEE ALSO 

bgnpoi, endpoi, v 

NOTE 

pnt should not be used in new development Rather, points should be | 
drawn using the high-performance v commands, surrounded by calls to ^ 
bgnpoi and endpoi. 



c 



c 
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NAME 

pntsmo - specify antialiasing of points 

FORTRAN 77 SPECIFICATION 

subroutine pntsmo(mode) 
integer*4 mode 

PARAMETERS 

mode expects one of two values: 

SMPOFF defeats antialiasing of points (default). 

SMPON enables antialiasing of points. It can be modified by an 
optional symbolic constant: 

SMPSMO indicates that a higher quality filter should be used 
during point drawing. This filter typically requires that more 
pixels be modified, and therefore potentially reduces the rate at 
which antialiased points are rendered. 

The constant SMPSMO is specified by bitwise ORing it, or by adding it, 
to SMPON. For example: 

pntsmo (SMPON + SMPSMO) 

enables antialiased point drawing with the highest quality, and poten- 
tially lowest performance, algorithm. The modifier is a hint, not a direc- 
tive, and is therefore ignored by systems that do not support the 
requested feature. 

DESCRIPTION 

pntsmo controls the capability to draw antialiased points. You can 
draw antialiased points in either color map mode or RGB mode. 

For color map antialiased points to draw correctly, you must initialize a 
16-entry colormap block (whose lowest entry location is a multiple of 
16) to a ramp between the background color (lowest index) and the 
point color (highest index). Before drawing points, clear the area to the 
background color. 
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The pntsmooth hardware replaces the least significant 4 bits of the 
current color index with bits that represent pixel coverage. Therefore, 
by changing the current color index (only the upper 8 bits are 
significant) you can select among many 16-entry color ramps, represent- 
ing different colors and intensities. You can draw depthcued antialiased 
points in this manner. 

The z-buffer hardware can be used to improve the quality of color map 
antialiased point images. Enabled in the standard depth-comparison 
mode, it ensures that points nearer the viewer obscure more distant 
points. Alternately, the z-buffer hardware can be used to compare color 
values by issuing: 

zbuffe(.TRUE.) 
zsourc (ZSRCCO) 
zf unct (ZFGREA) 

Pixels are then replaced only by 'brighter' values, resulting in better 
intersections between points drawn using the same ramp. 

RGB antialiased points can be drawn only on machines that support 
blending. For these points to draw correctly, the blendfunction must be 
set to merge new pixel color components into the framebuffer using the 
incoming (source) alpha values. Incoming color components should 
always be multiplied by the source alpha (BFSA). Current (destination) 
color components can be multiplied either by one minus the source 
alpha (BFMSA), resulting in a weighted average blend, or by one 
(BFONE), resulting in color accumulation to saturation; issue: 

c weighted average 

blendf(BFSA, BFMSA) 



or 



saturation 
blendf(BFSA, BFONE) 



The pntsmooth hardware scales incoming alpha components by an 8-bit 
computed coverage value. Therefore reducing the incoming source 
alpha results in transparent, antialiased points. 



c 



( 



o 
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RGB antialiased points draw correctly over any background image. It is 
not necessary to clear the area in which they are to be drawn. 

Both color map and RGB mode points are antialiased effectively only 
when subpixel mode is enabled; issue: 

subpix ( . TRUE . ) 

The modifier SMPSMO can be ORed or ADDed to the symbolic con- 
stant SMPON when antialiased points are enabled. When this is done, a 
higher quality and potentially lower performance filter is used to scan 
convert antialiased points. SMPSMO is a hint, not a directive. Thus a 
higher quality filter is used only if it is available. 

SEE ALSO 

bgnpoi, blendf, endpoi, gversi, linesm, subpix, v, zbuffe, zfunct, zsourc 

NOTES 

This routine does not function on IRIS-4D B or G models, or on early 
serial numbers of the Personal Iris. Use gversi to determine which type 
you have. 

IRIS-4D GT and GTX models, and the Personal Iris, do not support 
SMPSMO. These systems ignore this hint. 



BUGS 



Color-comparison z-buffering is not supported on the IRIS-4D GT or 
GTX models. 
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NAME 

polarv - defines the viewer's position in polar coordinates 

FORTRAN 77 SPECIFICATION 

subroutine polarv(dist ? azim, inc, twist) I 

real dist ^ 

integer*4 azim, inc, twist 

PARAMETERS 

dist expects the distance from the viewpoint to the world space origin. 

azim expects the azimuthal angle in the x-y plane, measured from the y 
axis. The azimuth angle is the viewing angle of the observer. 

inc expects the angle of incidence in the y-z plane, measured from 
the z axis. The incidence angle is the angle of the viewport rela- 
tive to the z axis. 



twist expects the amount that the viewpoint is to be rotated around the 
line of sight using the right-hand rule. 

DESCRIPTION 

polarv defines the viewer's position in polar coordinates. It sets up a 
right-hand world coordinate system with x to the right, y straight up, and 
z towards the viewer. The line of sight extends from the viewpoint 
through the world space origin. All angles are specified in tenths of 
degrees and are integers. 

The matrix computed by polarv premultiplies the current matrix, which 
is chosen based on the current matrix mode. 

SEE ALSO 

mmode, lookat 



c 



c 
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NAME 

polf, polfi, polfs, polf2, po!f2i, polf2s - draws a filled polygon 

FORTRAN 77 SPECIFICATION 

subroutine polf(n, parray) 
integer*4 n 
real parray(3,n) 

subroutine polfi(n, parray) 
integer*4 n 
integer*4 parray(3,n) 

subroutine polfs(n, parray) 
integer*4 n 
integer*2 parray(3,n) 

subroutine polf2(n, parray) 
integer*4 n 
real parray(2,n) 

subroutine polf2i(n, parray) 
integer*4 n 
integer*4 parray(2,n) 

subroutine polf2s(n, parray) 
integer*4 n 
integer*2 parray(2,n) 

All of the above routines are functionally the same. They differ only in 
the declared type of their parameters and whether or not they assume a 
two-dimensional or three-dimensional world. 

PARAMETERS 

n expects the number of points in the polygon. 

parray expects the array containing the vertices of the polygon. 

DESCRIPTION 

polf fills polygonal areas using the current pattern, color, and writemask. 
Polygons are represented as arrays of points. The first and last points 
connect automatically to close a polygon. The points can be expressed 
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as integers, shorts, or real numbers, in 2-D or 3-D space. 2-D polygons 
are drawn with z=0. After the polygon is filled, the current graphics 
position is set to the first point in the array. 

There can be no more than 256 points (corners) in a polygon. In addi- 
tion, polf cannot correctly draw polygons that intersect themselves. 

SEE ALSO 

concav, poly, rect, rectf, pdr, pmv, rpdr, rpmv 



c 



() 



Version 3.0 - 2 - April 1990 



poly Graphics Reference, FORTRAN poly 

NAME 

poly, polyi, polys, poly2, poly2i, poly2s - outlines a polygon 

FORTRAN 77 SPECIFICATION 

subroutine poly(n, parray) 
integer*4 n 
real parray(3,n) 

subroutine polyi(n, parray) 
integer*4 n 
integer*4 parray(3,n) 

subroutine polys(n, parray) 
integer*4 n 
integer*2 parray(3,n) 

subroutine poly2(n, parray) 
integer*4 n 
real parray(2 ? n) 

subroutine poly2i(n, parray) 
integer*4 n 
integer*4 parray(2,n) 

subroutine poly2s(n, parray) 
integer*4 n 
integer*2 parray(2,n) 

All of the above routines are functionally the same. They differ only in 
the type declarations of their parameters and in whether they assume a 
two- or three-dimensional space. 

PARAMETERS 

n expects the number of points in the polygon. 

parray expects the array containing the vertices of the polygon. 

DESCRIPTION 

poly outlines a polygon. A polygon is represented as an array of points. 
The first and last points connect automatically to close the polygon. The 
points can be expressed as integers, shorts, or real numbers, in 2-D or 
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3-D space. 2-D polygons are drawn with z=0. The polygon is outlined 
using the current linestyle, linewidth, color, and writemask. The max- 
imum number of points in a polygon is 256. 

SEE ALSO jT 

polf, rect, rectf, pmv, pdr, pclos, rpmv, rpdr ^ 



c 



( 
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NAME 

polymo - control the rendering of polygons 

FORTRAN SPECIFICATION 

subroutine polymo(mode) 
integer*4 mode 

PARAMETERS 

mode Expects one of the symbolic constants: 

PYMPOI, draw only points at the vertices. 
PYMLIN, draw lines from vertex to vertex. 
PYMFIL, fill the polygon interior. 
PYMHOL, fill only interior pixels at the boundaries. 

DESCRIPTION 

polymo specifies whether polygons are filled, outlined, drawn with 
points at their vertices, or outlined with a hollow fill algorithm. 
Affected polygons include all polygons that are normally filled, includ- 
ing those generated by bgnpol and endpol, by bgntme and endtme, by 
bgnqst and endqst, by arcf, circf, and rectf, and by NURBS surfaces. 
Also affected are polygons generated by the obsolete pmv, pdr, and 
pclos commands, and by polf and spolf. 

PYMFIL is the default mode. In this mode polygons are filled with a 
point-sample algorithm. (Refer to the Graphics Library Programmer's 
Guide for an detailed explanation of point-sampling.) 

PYMPOI causes a single point to be drawn at each polygon vertex, 
including vertices generated by clipping. All point rendering modes, 
including antialiasing specified by pntsmo, apply to these points. 

PYMLIN causes lines to be drawn from vertex to vertex around the per- 
imeter of the polygon. This line forms a single outline, because it 
passes through both projected vertices and vertices generated by clip- 
ping. All line rendering modes, including line width, line stipple style, 
and line antialiasing specified by linesm, apply to these lines. 
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PYMHOL supports a special kind of polygon fill with the following 
properties: 

1. Only pixels on the polygon edge are filled. These pixels form a 
single- width line (regardless of the current linewi) around the inner 
perimeter of the polygon. 

2. Only pixels that would have been filled (PYMFIL) are changed (i.e. 
the outline does not extend beyond the exact polygon boundary). 

3. Pixels that are changed take the exact color and depth values that 
they would have had the polygon been filled. 

Because their pixel depth values are exact, hollow polygons can be com- 
posed with filled polygons accurately. Both hidden-line and scribed- 
surface renderings can be done taking advantage of this fact 

SEE ALSO 

bgnpol, endpol, polysm, stenci 

NOTES 

IRIS-4D G, GT, and GTX models, and the Personal Iris, do not support 
polymo. Use getgde to determine whether support for polymo is avail- 
able. 



BUGS 



In order to support polygon fill mode PYMHOL, IRIS-4D VGX models 
require that the following conditions be met: 

1 . Stencil planes be allocated (at least one plane). 

2. The stencil planes be initialized to zero prior to drawing hollow 
polygons. 

3. The stencil planes be used for no other purpose while drawing hol- 
low polygons. (The stencil function is controlled by the hardware 
and must not be user specified.) 

IRIS-4D VGX models have an error in their microcode that results in 
matching errors between pixels generated by PYMFIL and PYMHOL 
in some conditions. This error will be corrected in the next software 
release. 



Version 3.0 - 2 - April 1990 



c 



( 



c 



polysm Graphics Reference, FORTRAN polysm 

NAME 

polysm - specify antialiasing of polygons 

FORTRAN SPECIFICATION 

subroutine polysm(mode) 
integer*4 mode 

PARAMETERS 

mode Expects one of the symbolic constants: 

PYSMOF: do not antialias polygons, (default) 

PYSMON: compute coverage values for all perimeter polygon 
pixels in such a way as to not change the size of the polygon. 

PYSMSH: Compute coverage values for all perimeter polygon 
pixels in such a way as to shrink the polygon slightly. 

DESCRIPTION 

polysm specifies one-pass antialiasing of polygons. Unlike pntsmo and 
linesm, it is available only in RGB mode. Also, unlike pntsmo and 
linesm, its use in complex scenes requires attention to primitive drawing 
order if acceptable results are to be achieved. Thus polysm use is some- 
what more complex than that of pntsmo and linesm. 

Like points and lines, polygons are antialiased by computing a coverage 
value for each scan-converted pixel, and using this coverage value to 
scale pixel alpha. Thus, for RGB antialiased polygons to draw 
correctly, blendf must be set to merge new pixel color components with 
the previous components using the incoming alpha. In the simplistic 
case of adding a single, antialiased polygon to a previously rendered 
scene, the same blendf as is typically used for point and line antialiasing 
can be used: 

blendf(BFSA, BFMSA) . 

Pixels in the interior of the polygon will have coverage assigned to 1.0, 
and will therefore replace their framebuffer counterparts. Pixels on the 
perimeter of the polygon are blended into the framebuffer in proportion 
to their computed coverage. 
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A more typical case, however, is that of antialiasing the polygons that 
comprise the surface of a solid object. Here the standard blendf will 
result in leakage' of color between adjacent polygons. For example, if 
the first polygon drawn covers a sample pixel 40%, and the second 
(adjacent) polygon covers the pixel 60%, the net coverage of %100 still 
leaves %24 background color in the pixel. 

If the solid object is to be correctly antialiased, with no leakage through 
interior edges, and with proper silhouettes, the following rules must be 
followed: 

1 . Polygons must be drawn in view order from nearest to farthest. (Not 
farthest to nearest as is done with transparency.) 

2. Polygons that face away from the viewer must not be drawn. (Use 
backf a ( . TRUE . ) .) 

3. The special blendf (BFMINS, BFONE) must be used to blend 
polygons into the framebuffer. 

4. Polysmooth mode PYSMON must be used. 

The special polysmooth mode PYSMSH specifies a coverage algorithm 
that includes only pixels that would have been scan-converted had the 
mode been PYSMOF. (PYSMON includes pixels that are outside that 
range of those point-sampled by the PYSMOF algorithm.) PYSMSH 
necessarily leaks background color between adjacent polygons, but does 
this in a way that resembles antialiased lines. Thus, PYSMSH can be 
used in conjunction with blendf (BFSA, BFZERO) , and with no 
sorting of polygons (use the z-buffer), to generate solid images 
tesselated with black, antialiased lines. 

SEE ALSO 

linesm, pntsmo, blendf, subpix 

NOTES 

IRIS-4D G, GT, and GTX models, and the Personal Iris, do not support 
polysm. Use getgde to determine whether polysm is supported. 



c 
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subpix mode should always be enabled while polysm is used. 



BUGS 



IRIS-4D VGX models reveal their decomposition of 4+ sided polygons 
into triangles when PYSMSH is selected. This behavior is not 
intended, and may not be duplicated by future VGX software releases, 
or by future models. 
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NAME 

popatt - pops the attribute stack 

FORTRAN SPECIFICATION 
subroutine popatt 

PARAMETERS 

none 



( 



DESCRIPTION 

popatt pops the attribute stack, restoring the values of the global state 
attributes listed below that were most recently saved with pushat. 



Attributes 


backbuffer 




linewidth 


cmode or RGBmode 


Isrepeat 


color 




pattern 


drawmode 




font 


frontbuffer 




RGB color 


linestyle 




RGB writemask 


writmask 




shademodel 



c 



SEE ALSO 

backbu, cmode, color, drawmo, frontb, linewi, lsrepe, pushat, RGBcol, 
RGBwri, setlin, setpat, shadem, writem 



c 
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NAME 

popmat - pops the transformation matrix stack 

FORTRAN 77 SPECIFICATION 
subroutine popmat 

PARAMETERS 

none 

DESCRIPTION 

popmat pops the transformation matrix stack. It operates on the single 
transformation stack when mmode is MSINGL, and on the ModelView 
matrix stack when mmode is MVIEWI. It should not be called when 
mmode is MPRO JE or MTEXTU. 

popmat is ignored when there is only one matrix on the stack. 

SEE ALSO 

getmat, loadma, mmode, multma, pushma 
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NAME 

popnam - pops a name off the name stack 

FORTRAN 77 SPECIFICATION 
subroutine popnam 

PARAMETERS 
none 

DESCRIPTION 

popnam removes the top name from the name stack. It is used in pick- 
ing and selecting. 

popnam is ignored outside of picking and selecting mode. 

SEE ALSO 

gselec loadna, pushna, pick 



c 



c 
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NAME 

popvie - pops the viewport stack 

FORTRAN SPECIFICATION 
subroutine popvie 

PARAMETERS 

none 

DESCRIPTION 

popvie pops the viewport stack, restoring the values of the viewport, 
screenmask, and depth range most recently saved with pushvi. 

SEE ALSO 

lsetde, pushvi, scrmas, viewpo 
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NAME 

prefpo - specifies the preferred location and size of a graphics window 

FORTRAN 77 SPECIFICATION 

subroutine prefpo(xl, x2, yl, y2) 
integer*4 xl, x2, yl, y2 

PARAMETERS 

xl expects the x coordinate position (in pixels) of the point at which 
one corner of the window is to be. 

x2 expects the x coordinate position (in pixels) of the point at which 
the opposite corner of the window is to be. 

yl expects the y coordinate position (in pixels) of the point at which 
one corner of the window is to be. 

y2 expects the y coordinate position (in pixels) of the point at which 
the opposite corner of the window is to be. 

DESCRIPTION 

prefpo specifies the preferred location and size of a graphics window. 
You specify the location in pixels (xl, x2, yl, yl). Call prefpo at the 
beginning of a graphics program. Use prefpo with wincon to modify 
the enforced size and location after the window has been created. Cal- 
ling winope activates the constraints specified by prefpo. If winope is 
not called, prefpo is ignored. 

SEE ALSO 

wincon, winope 

NOTE 

This routine is available only in immediate mode. 



( 



( 



( 
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NAME 

prefsi - specifies the preferred size of a graphics window 

FORTRAN 77 SPECIFICATION 

subroutine prefsi(x, y) 
integer*4 x, y 

PARAMETERS 

x expects the width of the graphics window. The width is measured in 
pixels. 

y expects the height of the graphics window. The height is measured 
in pixels. 

DESCRIPTION 

prefsi specifies the preferred size of a graphics window as x pixels by y 
pixels. Call prefsi at the beginning of a graphics program. 

Once a window is created, you must use prefsi with wincon in order to 
modify the enforced window size. Calling winope activates the con- 
straints specified by prefsi. If winope is not called, prefsi is ignored. 

SEE ALSO 

wincon, winope 

NOTE 

This routine is available only in immediate mode. 
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NAME 

pupmod, endpup - obsolete routines 

FORTRAN 77 SPECIFICATION 
subroutine pupmod 
subroutine endpup 

PARAMETERS 

none 

DESCRIPTION 

These routines are obsolete. Although pupmode/endpupmode con- 
tinue to function (to provide backwards compatibility) all new develop- 
ment should use drawmo to access the pop-up menu bitplanes. 

SEE ALSO 
drawmo 



( 
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pushat 



NAME 

pushat - pushes down the attribute stack 

FORTRAN 77 SPECIFICATION 
subroutine pushat 

PARAMETERS 

none 

DESCRIPTION 

pushat pushes down the attribute stack, duplicating the following global 
state attributes: 



Attributes 


backbuffer 




linewidth 


cmode or RGBmode 


Isrepeat 


color 




pattern 


drawmode 




font 


frontbuffer 




RGB color 


linestyle 




RGB writemask 


writmask 




shademodel 



The saved values can be restored using popatt. 

The attribute stack is ATTRIBSTACKDEPTH levels deep, pushat is 
ignored if the stack is full. 

SEE ALSO 

backbu, cmode, color, drawmo, frontb, linewi, Isrepe, popatt, RGBcol, 
RGBmod, RGBwri, setlin, setpat, shadem, writem 



Version 3.0 



April 1990 



pushma Graphics Reference, FORTRAN pushma 

NAME 

pushma - pushes down the transformation matrix stack 

FORTRAN 77 SPECIFICATION 

subroutine pushma f 

PARAMETERS 
none 

DESCRIPTION 

pushma pushes down the transformation matrix stack, duplicating the 
current matrix. For example, if the stack contains one matrix, M, after a 
call to pushma, the stack contains two copies of M. Only the top copy 
can be modified. 

pushma operates on the single transformation stack when mmode is 
MSINGL, and on the ModelView matrix stack when mmode is 
MVIEWI. It should not be called when mmode is MPROJE or 
MTEXTU. £ 

SEE ALSO 

getmat, loadma, mmode, multma, popmat 



( 
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NAME 

pushna - pushes a new name on the name stack 

FORTRAN 77 SPECIFICATION 

subroutine pushna(name) 
integer*4 name 

PARAMETERS 

name expects the name which is to be added onto the name stack. 

DESCRIPTION 

pushna pushes the name stack down one level, and puts a new 16-bit 
name on top. The system stores the contents of the name stack in a 
buffer for each hit in picking and selecting modes. 

pushna is ignored outside of picking and selecting mode. 

SEE ALSO 

gselec, popnam, loadna, pick 
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NAME 

pushvi - pushes down the viewport stack 

FORTRAN 77 SPECIFICATION 

subroutine pushvi f 

PARAMETERS 

none 

DESCRIPTION 

pushvi pushes down the viewport stack, duplicating the current 
viewport, screenmask, and depth range. These saved values can be 
restored using popvie. 

The viewport stack is VPSTACKDEPTH levels deep, pushvi is ignored 
if the stack is full. 

SEE ALSO 

Isetde, popvie, sennas, viewpo 1 



c 
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NAME 

pw 

faces 



pwlcur - describes a piecewise linear trimming curve for NURBS sur- 



FORTRAN 77 SPECIFICATION 

subroutine pwlcur(n, dataarray, bytesize, type) 
integer*4 n, bytesize, type 
double precision dataarray(*) 

PARAMETERS 

n expects the number of points on the curve 

dataarray expects an array containing the curve points 

bytesize expects the offset (in bytes) between points on the curve 

type expects a value indicating the point type. Currently, the 

only data type supported is NST, corresponding to pairs of 
s-t coordinates. The offset parameter is used in case the 
curve points are part of an array of larger structure ele- 
ments, pwlcur searches for the n-th coordinate pair begin- 
ning at dataarray + n x bytesize. 

DESCRIPTION 

Use pwlcur to describe a piecewise linear curve. A piecewise linear 
curve consists of a list of pairs of coordinates of points in the parameter 
space for the NURBS surface. These points are connected together with 
straight lines to form a path. If a piecewise linear curve is an approxi- 
mation to a real curve, the points should be close enough together that 
the resulting path will appear curved at the resolution used in the appli- 
cation. 

You use piecewise linear curves within trimming loop definitions. A 
trimming loop definition is a set of oriented curve commands that 
describe a closed loop. To mark the beginning of a trimming loop 
definition, use the bgntri command. To mark the end of a trimming 
loop definition, use an endtri command. 
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You use trimming loop definitions within NURBS surface definitions 
(see bgnsur). The trimming loops are closed curves that the system uses 
to set the boundaries of a NURBS surface. You can describe a trimming 
loop by using a series of piecewise linear curves or NURBS curves (see 
nurbsc), or both. 

When the system needs to decide which part of a NURBS surface you 
want it to display, it displays the region of the NURBS surface that is to 
the left of the trimming curves as the parameter increases. Thus, for a 
counter-clockwise oriented trimming curve, the displayed region of the 
NURBS surface is the region inside the curve. For a clockwise oriented 
trimming curve, the displayed region of the NURBS surface is the 
region outside the curve. 

See the Graphics Library Programming Guide for a mathematical 
description of a NURBS curve. 

SEE ALSO 

bgnsur, nurbss, bgntri, nurbsc, setnur, getnur 



c 
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NAME 

qdevic - queues a device 

FORTRAN 77 SPECIFICATION 

subroutine qdevic(dev) 
integer*4 dev 

PARAMETERS 

dev expects the device whose state is to be changed so that it will enter 
events into the event queue. 

DESCRIPTION 

qdevic changes the state of the specified device so that events occurring 
within the device are entered in the event queue. The event queue con- 
tains a time-ordered list of input events. The device can be the key- 
board, a button, a valuator, or certain other pseudo-devices. 

The maximum number of queue entries is 101. 

SEE ALSO 

noise, tie, unqdev 

NOTE 

This routine is available only in immediate mode. 
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NAME 

qenter - creates an event queue entry 

FORTRAN 77 SPECIFICATION 

subroutine qenter(dev, val) ^ 

integer*4 dev, val 

PARAMETERS 

dev expects the device number to be entered into the event queue. 
val expects the value to be entered into the event queue. 

DESCRIPTION 

qenter takes a 16-bit device number and 16-bit a value and enters them 
into the event queue of the calling process. There is no way to distin- 
guish user-generated and system-generated events except by device 
number. 



The 16-bit device number name space is partitioned as follows: 

$0000 -> $0FFF Devices denned by SGI 

$0001 -> $00FF Buttons 

$0100 -> $01FF Valuators 

$0200 -> $02FF Pseudo devices 

$0300 -» $0EFF Reserved 

$0F00 -> $0FFF Additional buttons 

$1000 -» $7FFF Devices denned by users 

$1000 -> $2FFF Buttons 

$3000 -> $3FFF Valuators 

$4000 -» $7FFF Pseudo devices 

$8000 -> $FFFF Can not be used 

SEE ALSO 

qcontr, qread, qreset, qtest 



c 
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NOTE 

This routine is available only in immediate mode. 
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NAME 

qgetfd - returns the file descriptor of the event queue 

FORTRAN 77 SPECIFICATION 

integer*4 function qgetfd | 

PARAMETERS 
none 

FUNCTION RETURN VALUE 

The returned function value is the file descriptor associated with the 
event queue. If there was is error, the returned value is a negative 
integer whose absolute value is an error value defined in <errno.h>. 

DESCRIPTION 



qgetfd returns the file descriptor associated with the event queue. The 
file descriptor can then be used with the select(2) system call. 

SEE ALSO 

qread 

select(2) in the Programmer's Reference Manual. 

NOTES 

This routine is available only in immediate mode. 

This routine is not available in the Distributed Graphics Library. 



c 



( 



Version 3,0 -1- April 1990 



qread Graphics Reference, FORTRAN qread 

NAME 

qread - reads the first entry in the event queue 

FORTRAN 77 SPECIFICATION 

integer*4 function qread(data) 
integer*2 data 

PARAMETERS 

data 

expects the variable that is to receive the data the event queue. 

FUNCTION RETURN VALUE 

The returned function value is the identifier for the device read. 

DESCRIPTION 

When there is an entry in the queue, qread returns the device number of 
the queue entry, writes the data of the entry into data, and removes the 
entry from the queue. 

If there is not an entry in the queue, qread will block and return when 
an entry is made. 

SEE ALSO 

qreset, qtest 

NOTE 

This routine is available only in immediate mode. 
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NAME 

qreset - empties the event queue 

FORTRAN 77 SPECIFICATION 

subroutine qreset | 

PARAMETERS 
none 

DESCRIPTION 

qreset removes all entries from the event queue and discards them. 

SEE ALSO 

qenter, qread, qtest 



NOTE 

This routine is available only in immediate mode. 



c 



c 
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NAME 

qtest - checks the contents of the event queue 

FORTRAN 77 SPECIFICATION 
integer*4 function qtest 

PARAMETERS 

none 

DESCRIPTION 

qtest returns zero if the queue is empty. Otherwise, it returns the device 
number of the first entry. The queue remains unchanged. 

SEE ALSO 

qenter, qread, qreset 

NOTE 

This routine is available only in immediate mode. 
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NAME 

rcrv - draws a rational curve 

FORTRAN 77 SPECIFICATION 

subroutine rcrv(geom) 
real geom(4,4) 

PARAMETERS 

geom expects the array containing the four control points of the curve 
segment 

DESCRIPTION 

rcrv draws a rational cubic spline curve segment using the current curve 
basis and curve precision, geom specifies the four control points of the 
curve segment. 

The curve segment is approximated by a sequence of straight lines. All 
lines use the current linestyle, which is reset prior to the first line and 
continues through subsequent lines. Other line modes, including depth- 
cueing, line width, and line antialiasing, also apply to the lines gen- 
erated by rcrv. 

After rcrv executes, the graphics position is undefined. 

SEE ALSO 

crv, crvn, curveb, curvep, defbas, depthc, linesm, linewd, rcrvn, setlin 
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NAME 

rcrvn - draws a series of curve segments 

FORTRAN 77 SPECIFICATION 

subroutine rcrvn(n, geom) | 

integer*4n ^ 

real geom(4,n) 

PARAMETERS 

n expects the number of control points to be used in drawing the 
curve. 

geom expects the matrix containing the control points of the curve seg- 
ments. 

DESCRIPTION 



rcrvn draws a series of rational cubic spline curve segments using the 
current basis and precision. The control points specified in geom deter- 
mine the shapes of the curve segments and are used four at a time. For 
example, if n is 6, three curve segments are drawn, the first using points 
0,1,2,3 as control points, and the second and third segments are con- 
trolled by points 1,2,3,4 and 2,3,4,5, respectively. If the current basis is 
a B-spline, Cardinal spline, or basis with similar properties, the curve 
segments are joined end to end and appear as a single curve. 

Each curve segment is approximated by a sequence of straight lines. All 
lines use the current linestyle, which is reset prior to the first line and 
continues through subsequent lines. Other line modes, including depth- 
cueing, line width, and line antialiasing, also apply to the lines gen- 
erated by rcrvn. 

After rcrvn executes, the graphics position is undefined. 

SEE ALSO 

crv, crvn, curveb, curvep, defbas, depthc, linesm, linewd, rcrv, setlin 



c 
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NAME 

rdr, rdri, rdrs, rdr2, rdr2i, rdr2s - relative draw 

FORTRAN 77 SPECIFICATION 

subroutine rdr(dx, dy, dz) 
real dx, dy, dz 

subroutine rdri(dx, dy, dz) 
integer*4 dx, dy, dz 

subroutine rdrs(dx, dy, dz) 
integer*2 dx, dy, dz 

subroutine rdr2(dx, dy) 
real dx, dy 

subroutine rdr2i(dx, dy) 
integer*4 dx, dy 

subroutine rdr2s(dx, dy) 
integer*2 dx, dy 

All of the above routines are functionally the same. They differ only in 
the type declarations of their parameters and whether or not they assume 
a two- or three-dimensional space. 

PARAMETERS 

dx expects the distance from the x coordinate of the current graphics 
position to the x coordinate of the new point. 

dy expects the distance from the y coordinate of the current graphics 
position to the y coordinate of the new point. 

dz expects the distance from the z coordinate of the current graphics 
position to the z coordinate of the new point. 
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DESCRIPTION 

rdr is the relative version of draw. It connects the current graphics 
position and a point, at the specified distance, with a line segment using 
the current linestyle, linewidth, color (if in depth-cue mode, the depth- 
cued color is used), and writemask. The system updates the current ^ 
graphics position to the new point. V. 

Do not place routines that invalidate the current graphics position within 
sequences of relative moves and draws. 

SEE ALSO 

bgnlin, endlin, popmat, pushma, rmv, transl, v 



NOTE 



rdr should not be used in new development. Rather, lines should be 
drawn using the high-performance v commands, surrounded by calls to 
bgnlin and endlin. Matrix commands pushma, transl, and popmat 
should be used to accomplish relative positioning. 



( 
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NAME 

readpi - returns values of specific pixels 

FORTRAN SPECIFICATION 

integer*4 function readpi(n, colors) 
integer*4 n 
integer*2 colors(n) 

PARAMETERS 

n expects the number of pixels to be read by the function. 

colors expects the array in which the pixel values are to be stored. 

FUNCTION RETURN VALUE 

The returned value of this function is the number of pixels actually read. 
A returned function value of indicates an error, that the starting point 
is not a valid character position. 

DESCRIPTION 

readpi attempts to read up to n pixel values from the bitplanes in color 
map mode. It reads them into the array colors starting from the current 
character position along a single scan line (constant y) in the direction of 
increasing x. readpi returns the number of pixels read, which is the 
number requested if the starting point is a valid character position 
(inside the current viewport), readpi returns zero if the starting point is 
not a valid character position. The values of pixels read outside the 
viewport or the screen are undefined, readpi updates the current charac- 
ter position to one pixel to the right of the last one read; the current 
character position is undefined if the new position is outside the 
viewport. 

In double buffer mode, only the back buffer is read by default. On 
machines that support it, you can use readso to control which buffer is 
read. 
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The system must be in color map mode for readpi to function correctly. 

SEE ALSO 

Irectr, readso 

NOTES V 

readpi should not be used in new development. Rather, pixels should 
be read using the high-performance Irectr command. 

This routine is available only in immediate mode. 

The upper bits of a color value (an element of the colors array) are 
undefined. You can write this information to the frame buffer without 
problems. However, if you intend to interpret this data, be sure you 
mask out the upper bits. 



c 
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NAME 

readRG - gets values of specific pixels 

FORTRAN 77 SPECIFICATION 

integer*4 function readRG(n, red, green, blue) 

integer*4 n 

character*(*) red, green, blue 

PARAMETERS 

n expects the number of pixels to be read by the function. 

red expects the array in which the pixel red values will be stored. 

green expects the array in which the pixel green values will be stored. 

blue expects the array in which the pixel blue values will be stored. 

FUNCTION RETURN VALUE 

The returned value of this function is the number of pixels actually read. 
A returned function value of indicates an error, namely, that the start- 
ing point is not a valid character position. 

DESCRIPTION 

readRG attempts to read up to n pixel values from the bitplanes in RGB 
mode. It reads them into the red, green, and blue arrays starting from 
the current character position along a single scan line (constant y) in the 
direction of increasing x. readRG returns the number of pixels read, 
which is the number requested if the starting point is a valid character 
position (inside the current viewport). readRG returns zero if the start- 
ing point is not a valid character position. The values of pixels read out- 
side of the viewport or screen are undefined. 

readRG updates the current character position to one pixel to the right 
of the last one read; the current character position is undefined if the 
new position is outside the viewport. 
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In RGB double buffer mode, only the back buffer is read by default. On 
machines that support it, you can use readso to control which buffer is 
read. 

The system must be in RGB mode for readRG to function correctly. 

SEE ALSO 

lrectr, readso 

NOTES 

readRG should not be used in new development. Rather, pixels should 
be read using the high-performance lrectr command. 

This routine is available only in immediate mode. 



c 
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NAME 

readso - sets the source for pixels that various routines read 

FORTRAN 77 SPECIFICATION 

subroutine readso(src) 
integer*4 src 

PARAMETERS 

src expects a symbolic constant that identifies the pixel source that is to 
be used: 

SRCAUT selects the front color buffer when the current frame- 
buffer, as specified by drawmo, is in single buffer mode. It selects 
the back color buffer when the current framebuffer is in double 
buffer mode. This is the default 

SRCFRO selects the front color buffer of the current framebuffer, 
as specified by drawmo. This source is valid for both single buffer 
and double buffer operation. 

SRCB AC selects the back color buffer of the current framebuffer, 
as specified by drawmo. This source is valid only while the 
current framebuffer is in double buffer mode. 

SRCZBU selects the z-buffer of the current framebuffer. Because 
only the normal framebuffer has a z-buffer, this source is currently 
valid only while draw mode is NORMAL. 

SRCFRA selects the Live Video Digitizer as the pixel source, 
regardless of the current draw mode. This source is valid only on 
IRIS-4D GTX and VGX models with the Live Video Digitizer 
option board. IRIS-4D GTX models support this source only dur- 
ing rectco, not rectre or lrectr. 

SRCOVE selects the overlay planes, and is valid only while draw 
mode is NORMAL. This source is valid only on the Personal Iris. 

SRCUND selects the underlay planes, and is valid only while draw 
mode is NORMAL. This source is valid only on the Personal Iris. 
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SRCPUP selects the pop-up planes, and is valid only while draw 
mode is NORMAL. This source is valid only on the Personal Iris. 

DESCRIPTION 

readso specifies the pixel source buffer that rectco, readpi, readRG, 
rectre, and Irectr use. A separate read source is maintained for each of 
the GL firamebuffers: normal, pop-up, overlay, and underlay. Calls to 
readso change the read source of the currently active framebuffer, as 
specified by drawmo. By default the read source for each framebuffer 
isSRCAUT. 

Because read sources, with the exception of some implemented only on 
the Personal Iris, always specify a source within the current framebuffer, 
it is not possible to copy pixels from one framebuffer to another. Such a 
copy must be implemented by first reading pixels out of the source 
framebuffer, then changing the draw mode to the destination frame- 
buffer, and writing the pixels. 

SEE ALSO 

Irectr, readpi, readRG, rectco 

NOTES 

This subroutine is available only in immediate mode. 

This subroutine does not function on IRIS-4D B or G models. 

Read sources SRCOVE, SRCUND, and SRCPUP operate only on the 
Personal Iris. 

BUGS 

On the IRIS-4D GT and GTX models, and on the Personal IRIS, a sin- 
gle variable is shared between the four framebuffers. Separate variables 
will be implemented in the next software release. 

On some IRIS-4D GT and GTX models, while copying rectangles with 
blending active, readso also specifies the bank from which destination 
color and alpha are read (overriding the blendf setting). 



( 
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NAME 

rect, recti, rects - outlines a rectangular region 

FORTRAN 77 SPECIFICATION 

subroutine rect(xl, yl, x2, y2) 
real xl, yl, x2, y2 

subroutine recti(xl, yl, x2, y2) 
integer*4 xl, yl, x2, y2 

subroutine rects(xl, yl, x2,y2) 
integer*2 xl, yl, x2, y2 

All of the above routines are functionally the same. They differ only in 
the type declarations of their parameters. 

PARAMETERS 

xl expects the x coordinate of one of the corners of the rectangle. 

yl expects the y coordinate of one of the corners of the rectangle. 

x2 expects the x coordinate of the opposite corner of the rectangle. 

y2 expects the y coordinate of the opposite corner of the rectangle. 

DESCRIPTION 

rect draws an unfilled rectangle in the x-y plane with z assumed to be 
zero. The sides of the rectangle are parallel to the x and y axes. To 
create a rectangle that does not lie in the x-y plane, draw the rectangle in 
the x-y plane, then rotate and/or translate the rectangle. 

A rectangle is drawn as a sequence of four line segments, and therefore 
inherits all properties that affect the drawing of lines. These include the 
current color, writemask, line width, stipple pattern, shade model, line 
antialiasing mode, and subpixel mode. The stipple pattern is initialized 
to bit zero of the current linestyle before the rectangle is drawn, then 
shifted continuously through the segments of the rectangle. 
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After rect executes, the graphics position is undefined. 

SEE ALSO 

bgnclo, linewi, linesm, Isrepe, rectf, sbox, scrsub, setlin, shadem, subpix 



( 
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NAME 

rectco - copies a rectangle of pixels with an optional zoom 

FORTRAN 77 SPECIFICATION 

subroutine rectco(xl, yl, x2, y2, newx, newy) 
integer *4 xl, yl, x2, y2, newx, newy 

PARAMETERS 

xl expects the x coordinate of one corner of the rectangle. 

yl expects the y coordinate of one corner of the rectangle. 

x2 expects the x coordinate of the opposite corner of the rectangle. 

y2 expects the y coordinate of the opposite corner of the rectangle. 

newx expects the x coordinate of the lower-left corner of the new posi- 
tion of the rectangle. 

newy expects the y coordinate of the lower-left corner of the new posi- 
tion of the rectangle. 

DESCRIPTION 

rectco copies a rectangular array of pixels (xl,yl,x2,y2) to another 
position on the screen. The current viewport and screenmask mask the 
drawing of the copied region. Self-intersecting copies work correctly in 
all cases. 

Use readso to specify the front buffer, the back buffer, the z-buffer, or 
the optional Live Video Digitizer frame buffer as the source. When 
using the Live Video Digitizer as the readsource, the coordinate argu- 
ments should be specified relative to a video origin of (0,0). 

On machines that support it, you can use rectzo to independently zoom 
the destination in both the x and y directions. Self-intersecting copies 
with zoom also work correctly. Likewise, on machines that support it, 
pixmod can be used to greatly affect the copy operation. Pixel shifts, 
reflections, and numeric offsets are all possible. 
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Use frontb, backbu, and zdraw to specify the destination. All coordi- 
nates are relative to the lower-left corner of the window. 

The result of rectco is undefined if zbuffe is .TRUE., except when pixel 
mode PMZDAT is enabled (see pixmod). This special pixel mode, in 
conjunction with stencil operation, can be used to implement rectangle 
copies with depth buffering. 

rectco always operates within the currently active framebuffer, as 
specified by drawmo. 

rectco leaves the current character position unpredictable 

SEE ALSO 

pixmod, readso, rectzo, stenci 

NOTES 

This subroutine is available only in immediate mode. 

The Live Video Digitizer option is available only on IRIS-4D GTX and 
VGX models. 



BUGS 



Pixel format is not considered during the copy. For example, if you 
copy pixels that contain color index data into an RGB window, the 
display subsystem cannot correctly interpret it. 

On IRIS-4D GTX models the zoom factor is not applied when reading 
from the Live Video Digitizer's frame buffer. 



c 
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NAME 

rectf, rectfi, rectfs - fills a rectangular area 

FORTRAN 77 SPECIFICATION 

subroutine rectf(xl, yl, x2, y2) 
real xl, yl, x2, y2 

subroutine rectfi(xl, yl, x2, y2) 
integer*4 xl, yl, x2, y2 

subroutine rectfs(xl, yl, x2, y2) 
integer *2 xl, yl, x2, y2 

All of the above routines are functionally the same. They differ only in 
the type declarations of their parameters. 

PARAMETERS 

xl expects the x coordinate of one corner of the rectangle that is to be 
drawn. 

yl expects the y coordinate of one corner of the rectangle that is to be 
drawn. 

x2 expects the x coordinate of the opposite corner of the rectangle that 
is to be drawn. 

y2 expects the y coordinate of the opposite corner of the rectangle that 
is to be drawn. 

DESCRIPTION 

rect draws a filled rectangle in the x-y plane with z assumed to be zero. 
The sides of the rectangle are parallel to the x and y axes. To create a 
rectangle that does not lie in the x-y plane, draw the rectangle in the x-y 
plane, then rotate and/or translate the rectangle. 

A rectangle is drawn as a single polygon, and therefore inherits all pro- 
perties that affect the drawing of polygons. These include the current 
color, writemask, fill pattern, shade model, polygon antialiasing mode, 
polygon scan conversion mode, and subpixel mode. Front-face and 
back-face elimination work correctly with filled rectangles. The front- 
face of a rectangle faces the positive z half-space when (xl f yl) is the 
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lower-left corner of the rectangle in object coordinates. 
After rectf executes, the graphics position is undefined. 

SEE ALSO 

backfa, bgnpol, frontf, polymo, polysm, rect, scrsub, setpat, shadem, 
subpix 

NOTE 

Previous graphics library implementations set the current graphics posi- 
tion to (xl, yl) after the rectangle was drawn. Current graphics position 
is now undefined after a rectangle is drawn. 



c 



c 
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NAME 

rectre, Irectr - reads a rectangular array of pixels into CPU memory 

FORTRAN 77 SPECIFICATION 

integer*4 rectre(xl, yl, x2, y2, parray) 
integer*4 xl, yl, x2, y2 
integer*2 parray(*) 

integer*4 lrectr(xl, yl, x2, y2, parray) 
integer*4 xl, yl, x2, y2 
integer*4 parray(*) 

PARAMETERS 

xl expects the x coordinate of the lower-left corner of the rectangle 
that you want to read. 

yl expects the y coordinate of the lower-left corner of the rectangle 
that you want to read. 

x2 expects the x coordinate of the upper-right corner of the rectan- 
gle that you want to read. 

y2 expects the y coordinate of the upper-right corner of the rectan- 
gle that you want to read. 

parray expects the array to receive the pixels that you want to read. 

FUNCTION RETURN VALUE 

The returned value of this function is the number of pixels specified in 
the rectangular region, regardless of whether the pixels were actually 
readable (i.e. on-screen) or not. 
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DESCRIPTION 

rectre and Irectr read the pixel values of a rectangular region of the 
screen and write them to the array, parray. The system fills the elements 
of parray from left-to-right, then bottom-to-top. All coordinates are 
relative to the lower-left corner of the window, not the screen or 
viewport. 

rectre fills an array of 16-bit words, and therefore should be used only 
to read color index values. Irectr fills an array of 32-bit words. Based 
on the current pixmod, in can return pixels of 1, 2, 4, 8, 12, 16, 24, or 32 
bits each. Use it to read packed RGB or RGBA values, color index 
values, or z values. Use readso to specify the pixel source from which 
both rectre and Irectr read pixels. 

pixmod greatly affects the operation of Irectr, and has no effect on the 
operation of rectre. By default, Irectr returns 32-bit pixels in the for- 
mat used by cpack. Different pixel sizes, framebuffer shifts, scan pat- 
terns through the framebuffer, and strides through memory, can all be 
specified using pixmod 

rectre and Irectr leave the current character position unpredictable. 

SEE ALSO 

Irectw, pixmod, readso 

NOTES 

These routines are available only in immediate mode. 

On IRIS-4D GT and GTX models, returned bits that do not correspond 
to valid bitplanes are undefined. Other models return zero in these bits. 

On IRIS-4D GT, GTX, and VGX models, rectre performance will 
suffer if x2 - xl + 1 is odd, or if parray is not 32-bit word aligned. 



c 



( 
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NAME 

rectwr, lrectw - draws a rectangular array of pixels into the frame 
buffer 

FORTRAN 77 SPECIFICATION 

subroutine rectwr(xl, yl, x2, y2, parray) 
integer*4 xl, yl, x2, y2 
integer*2 parray(*) 

subroutine lrectw(xl, yl, x2, y2, parray) 
integer*4 xl, yl, x2, y2 
integer*4 parray(*) 

PARAMETERS 

xl expects the lower-left x coordinate of the rectangular region. 

yl expects the lower-left y coordinate of the rectangular region. 

x2 expects the upper-right x coordinate of the rectangular region. 

y2 expects the upper-right y coordinate of the rectangular region. 

parray expects the array which contains the values of the pixels to be 
drawn. For RGBA values, pack the bits thusly: $AABBGGRR, 
where: 

AA contains the alpha value, 
BB contains the blue value, 
GG contains the green value, and 
RR contains the red value. 

RGBA component values range from to $FF (255). The alpha 
value will be ignored if blending is not active and the machine 
has no alpha bitplanes. 

DESCRIPTION 

rectwr and lrectw draw pixels taken from the array parray into the 
specified rectangular frame buffer region. The system draws pixels left- 
to-right, then bottom-to-top. All coordinates are relative to the lower-left 
corner of the window, not the screen or viewport. All normal drawing 
modes apply. 
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The size of parray is always (x2-xl+l) x (y2-yl+l). If the zoom fac- 
tors set by rectzo are both 1.0, the screen region xl through x2 9 yl 
through y2, are filled. Other zoom factors result in filling past x2 and/or 
past y2 (xl 9 yl is always the lower-left corner of the filled region). 

rectwr draws an array of 16-bit words, and therefore should be used 
only to write color index values. Irectw draws an array of 32-bit words. 
Based on the current pixmod, in can draw pixels of 1, 2, 4, 8, 12, 16, 24, 
or 32 bits each. Use it to write packed RGB or RGBA values, color 
index values, or z values. 

pixmod greatly affects the operation of Irectw, and has no effect on the 
operation of rectwr. By default, Irectw draws 32-bit pixels in the for- 
mat used by cpack. Different pixel sizes, framebuffer shifts, scan pat- 
terns through the framebuffer, and strides through memory, can all be 
specified using pixmod. 

rectwr and Irectw leave the current character position unpredictable. 

SEE ALSO 

blendf, Irectr, pixmod, rectco, rectzo 

NOTES 

These routines are available only in immediate mode. 



c 



( 



c 
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NAME 

rectzo - specifies the zoom for rectangular pixel copies and writes 

FORTRAN 77 SPECIFICATION 

subroutine rectzo(xfactor, yfactor) 
real xfactor, yfactor 

PARAMETERS 

xfactor expects the multiplier of the rectangle in the x direction. 
yfactor expects the multiplier of the rectangle in the y direction. 

DESCRIPTION 

rectzo specifies independent x and y zoom factors that rectco, rectwr, 
and lrectw use. rectzo scales the source image by the numbers 
specified by xfactor and yfactor. If rectzo(2.0, 3.0) is called, and the 
following rectangle is copied: 

1 3 
5 7 

the copy will be: 

113 3 

113 3 

113 3 

5 5 7 7 

5 5 7 7 

5 5 7 7 

Although zoom factors are specified as floating point values, some 
graphics systems do not support fractional zooms. These systems round 
each floating point zoom factor to the nearest integer value. Systems 
that do support fractional zoom replicate source image pixels when the 
zoom factor is greater than 1.0, and decimate the source image when the 
zoom factor is less than 1.0. 
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By default, xfactor and yf actor are 1 .0. 

SEE ALSO 

lrectw, pixmod, rectco, rectwr 

NOTE V 

This subroutine is available only in immediate mode. 

IRIS-4D G, GT, and GTX models, and the Personal Iris, do not support 
fractional zoom. 



c 
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NAME 

resetl - controls the continuity of linestyles 

FORTRAN 77 SPECIFICATION 

subroutine resetl(b) 
logical b 

PARAMETERS 

b expects either .TRUE, or .FALSE.. 

.TRUE, causes the linestyle to be reset at the beginning of each line 
segment. 

.FALSE, causes the linestyle to be continued across the segments of 
a line. 

DESCRIPTION 

resetl enables or disable linestyle reset mode. This mode affects the 
reinitialization of the linestyle pattern between line segments. If it is 
enabled (the default), it causes the stippling of each segment of a line to 
start at the beginning of the linestyle pattern. If it is disabled, the lines- 
tyle is not reset between segments, and the stippling of one segment 
continues from where it left off at the end of the previous segment. 

Changing resetl from .FALSE, to .TRUE, in the middle of a line causes 
the linestyle to be reset. If resetl is .FALSE, when setlin is called, the 
linestyle does not change until resetl(.TRUE.) is issued. 
resetl(.TRUE.) also initializes the lsrepe factor to 1. 

SEE ALSO 

deflin, getres, lsrepe, setlin 

NOTES 

The setting of resetl is ignored for Graphics Library primitives such as 
arcs, circles, and curves, even though they are currently implemented 
using lines. 
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This routine only functions on IRIS-4D B and G models, and therefore 
we advise against its use in new development. 



( 



( 
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NAME 

reshap - sets the viewport to the dimensions of the current graphics 
window 

FORTRAN 77 SPECIFICATION 
subroutine reshap 

PARAMETERS 

none 

DESCRIPTION 

reshap sets the viewport to the dimensions of the current graphics win- 
dow. Call it whenever REDRAW events are received for windows 
whose size is unconstrained, and therefore could have changed. 

reshap is equivalent to: 

integerM xsize, ysize 

call getsiz (xsize, ysize) 

call viewpo(0, xsize-1, 0, ysize-1) 

SEE ALSO 

getori, getsiz, viewpo 

NOTE 

This routine is available only in immediate mode. 
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NAME 

RGBcol - sets the current color in RGB mode 

FORTRAN 77 SPECIFICATION 

subroutine RGBcol(red, green, blue) | 

integer*4 red, green, blue ^ 

PARAMETERS 

red expects the value indicating the intensity of the red component. 

green expects the value indicating the intensity of the green com- 
ponent. 

blue expects the value indicating the intensity of the blue component. 
DESCRIPTION 



RGBcol sets the red, green, and blue color components of the currently 
active GL framebuffer, one of normal, popup, overlay, or underlay as 
specified by drawmo, to the specified values. Alpha, when supported, 
is set to the maximum value. The current framebuffer must be in RGB 
mode for the RGBcol command to be applicable. Most drawing com- 
mands copy the current RGB A color components into the color bit- 
planes of the current framebuffer. Color components are retained in 
each draw mode, so when a draw mode is re-entered, red, green, blue, 
and alpha are reset to the last values specified in that draw mode. 

Color component values range from 0, specifying no intensity, through 
255, specifying maximum intensity. Values that exceed 255 are 
clamped to it. Values less than are not clamped, and therefore result 
in unpredictable operation. 

It is an error to call RGBcol while the current framebuffer is in color 
map mode. 

The color components of all framebuffers in RGB mode are set to zero 
when gconfi is called. 



c 



( 
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SEE ALSO 

c, cpack, drawmo, gRGBco, lmcolo, RGBmod 



NOTE 



RGBcol can also be used to modify the current material while lighting 
is active (see lmcolo). 
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NAME 

RGBcur - obsolete routine 

FORTRAN 77 SPECIFICATION 

subroutine RGBcur(index, red, green, blue, redm, greenm, bluem) I 

integer*4 index, red, green, blue, redm, greenm, bluem ^ 

DESCRIPTION 

This routine is obsolete. It continues to function only on IRIS-4D B and 
G models to provide backwards compatibility. All new development 
should use its replacement, setcur. 

SEE ALSO 

setcur 

NOTE 

This routine is available only in immediate mode. 



( 
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NAME 

RGBmod - sets a rendering and display mode that bypasses the color 
map 

FORTRAN 77 SPECIFICATION 
subroutine RGBmod 

PARAMETERS 
none 

DESCRIPTION 

RGBmod instructs the system to treat color as a 4-component entity in 
the currently active drawmode. Currently RGB mode is supported only 
by the normal framebuffer, so RGBmod should be called only while in 
draw mode NORMAL. You must call gconfi for RGBmod to take 
effect. 

While in RGB mode, a framebuffer is configured to store separate color 
values for red, green, blue, and alpha components. Lighting, shading, 
and fog calculations are done in the true, RGB color space. Colors and 
writemasks must be specified using RGB-compatible commands such as 
c, cpack, and wmpack. The red, green, and blue components stored in 
the framebuffer are used (after correction for monitor non-linearity) to 
directly control the color guns of the monitor. 

Many advanced rendering features, such as complex lighting models, 
texture mapping, polygon antialiasing, and fog, are available only in 
RGB mode. 

SEE ALSO 

c, cmode, cpack, gammar, gconfi, getdis, getgde, wmpack 



NOTE 



RGBmod is not supported on all hardware configurations. The com- 
mand getgde can be used to determine how many bitplanes in the nor- 
mal framebuffer are available for each color component in both single 
and double buffered RGB mode. 
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This routine is available only in immediate mode. 



c 



( 
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NAME 

RGBran - obsolete routine 

FORTRAN 77 SPECIFICATION 

subroutine lRGBra(rmin, gmin, bmin, rmax, gmax, bmax, zl, z2) 
integer*2 rmin, gmin, bmin, rmax, gmax, bmax, zl, z2 

PARAMETERS 

rmin expects the minimum value to be stored in the red bitplanes. 

gmin expects the minimum value to be stored in the green bitplanes. 

bmin expects the minimum value to be stored in the blue bitplanes. 

rmax expects the maximum value to be stored in the red bitplanes. 

gmax expects the maximum value to be stored in the green bitplanes. 

hmax expects the maximum value to be stored in the blue bitplanes. 

zl expects the minimum z value that is to be used as criteria for 
linear mapping. 

z2 expects the maximum z value that is to be used as criteria for 
linear mapping. 

DESCRIPTION 

This routine is obsolete. Although it continues to function to provide 
backwards compatibility, all new development should use its replace- 
ment, lRGBra. 

SEE ALSO 
lRGBra 
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NAME 

RGBwri - grants write access to a subset of available bitplanes 

FORTRAN SPECIFICATION 

subroutine RGBwri(red, green, blue) 
integer*4 red, green, blue 

PARAMETERS 

red expects the mask for the corresponding red bitplanes. 
green expects the mask for the corresponding green bitplanes. 
blue expects the mask for the corresponding blue bitplanes. 

DESCRIPTION 

RGBwri sets the red, green, and blue write mask components of the 
currently active GL framebuffer, one of normal, popup, overlay, or 
underlay as specified by drawmo, to the specified values. The alpha 
mask component is set to enable writing to all alpha bitplanes. The 
current framebuffer must be in RGB mode for the RGBwri command to 
be applicable. All drawing into the color bitplanes of the current frame- 
buffer is masked by the current write mask. Write mask components are 
retained in each draw mode, so when a draw mode is re-entered, the red, 
green, blue, and alpha masks are reset to the last values specified in that 
draw mode. 

Each write mask component is an 8-bit mask, which allows changes 
only to bitplanes corresponding to ones in the mask. For example, 
RGBwri($F0,$00,$00) allows changes only to the 4 most significant 
bits of red, and to all the bits of alpha. Bits 8 through 15 of each com- 
ponent specification are ignored, only bits through 7 are significant. 

It is an error to call RGBwri while the current framebuffer is in color 
map mode. 

The write mask components of all framebuffers in RGB mode are set to 
$FF when gconfi is called. 



c 



c 
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SEE ALSO 

drawmo, gRGBma, RGBmod, wmpack 
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NAME 

ringbe - rings the keyboard bell 

FORTRAN 77 SPECIFICATION 

subroutine ringbe I 

PARAMETERS 

none 

DESCRIPTION 

ringbe rings the keyboard bell for the length of time set earlier by 
setbel. 

SEE ALSO 

clkon, lampon, setbel 

NOTE 

This routine is available only in immediate mode. I 
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NAME 

rmv, rmvi, rmvs, rmv2, rmv2i, rmv2s - relative move 

FORTRAN 77 SPECIFICATION 

subroutine rmv(dx, dy, dz) 
real dx, dy, dz 

subroutine rmvi(dx, dy, dz) 
integer*4 dx, dy, dz 

subroutine rmvs(dx, dy, dz) 
integer*2 dx, dy, dz 

subroutine rmv2(dx, dy) 
real dx, dy 

subroutine rmv2i(dx, dy) 
integer*4 dx, dy 

subroutine rmv2s(dx, dy) 
integer*2 dx, dy 

All of the above routines are functionally the same. They differ only in 
the type declarations of their parameters and in whether or not they 
assume a two- or three-dimensional space. 

PARAMETERS 

dx expects the distance from the x coordinate of the current graphics 
position to the x coordinate of the new graphics position. 

dy expects the distance from the y coordinate of the current graphics 
position to the y coordinate of the new graphics position. 

dz expects the distance from the z coordinate of the current graphics 
position to the z coordinate of the new graphics position. 

DESCRIPTION 

rmv is the relative version of move. It moves (without drawing) the 
graphics position the specified amount relative to its current value. 
rmv2(x, y) is equivalent to rmv(x, y, 0.0). 
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SEE ALSO 

bgnlin, endlin, popmat, pushma, rdr, transl, v 

NOTE 

rmv should not be used in new development. Rather, lines should be I 
drawn using the high-performance v commands, surrounded by calls to 
bgnlin and endlin. Matrix commands pushma, transl, and popmat 
should be used to accomplish relative positioning. 



c 
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NAME 

rotate, rot - rotate graphical primitives 

FORTRAN 77 SPECIFICATION 

subroutine rotate(a, axis) 
integer*4 a 
character axis 

subroutine rot(a, axis) 
real a 
character axis 

PARAMETERS 

a expects the angle of rotation of an object. 

axis expects the relative axis of rotation. There are three character 
literal values for this parameter: 

'x' indicates the x-axis. 

'y' indicates the y-axis. 

V indicates the z-axis. 

DESCRIPTION 

rotate and rot specify an angle (a) and an axis of rotation (axis). The 
angle given to rotate is an integer and is specified in tenths of degrees 
according to the right-hand rule. The angle given to rot is a floating 
point value and is specified in degrees according to the right-hand rule. 

These are modeling routines; they changes the current transformation 
matrix. All objects drawn after rotate or rot are rotated. Use pushma 
and popmat to preserve and restore an unrotated world space. 

SEE ALSO 

popmat, pushma, scale, transl 
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NAME 

rpatch - draws a rational surface patch 

FORTRAN 77 SPECIFICATION 

subroutine rpatch(geomx, geomy, geomz, geomw) 
real geomx(4,4), geomy(4,4), geomz(4,4), geomw(4,4) 

PARAMETERS 

geomx expects a 4x4 matrix containing the x coordinates of the 16 
control points of the patch. 

geomy expects a 4x4 matrix containing the y coordinates of the 16 
control points of the patch. 

geomz expects a 4x4 matrix containing the z coordinates of the 16 con- 
trol points of the patch. 

geomw expects a 4x4 matrix containing the w coordinates of the 16 
control points of the patch. 

DESCRIPTION 

rpatch draws a rational surface patch using the current patchb, patchp, 
and patchc which are defined earlier. The control points geomx, geomy, 
geomz geomw determine the shape of the patch. 

The patch is drawn as a web of curve segments. Each curve segment is 
approximated by a sequence of straight lines. All lines use the current 
linestyle, which is reset prior to the first line of each curve segment, and 
continues through subsequent lines in each curve segment. Other line 
modes, including depthcueing, line width, and line antialiasing, also 
apply to the lines generated by patch. 

SEE ALSO 

defbas, patch, patchb, patchc, patchp 



c 
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NAME 

rpdr, rpdri, rpdrs, rpdr2, rpdr2i, rpdr2s - relative polygon draw 

FORTRAN 77 SPECIFICATION 

subroutine rpdr(dx, dy, dz) 
real dx, dy, dz 

subroutine rpdri(dx, dy, dz) 
integer*4 dx, dy, dz 

subroutine rpdrs(dx, dy, dz) 
integer*2 dx, dy, dz 

subroutine rpdr2(dx, dy) 
real dx, dy 

subroutine rpdr2i(dx, dy) 
integer*4 dx, dy 

subroutine rpdr2s(dx, dy) 
integer*2 dx, dy 

All of the above routines are functionally the same. They differ only in 
the type declarations for their parameters and in whether they assume a 
two- or three-dimensional space. 

PARAMETERS 

dx expects the distance from the x coordinate of the current graphics 
position to the x coordinate of the next corner of the polygon. 

dy expects the distance from the y coordinate of the current graphics 
position to the y coordinate of the next corner of the polygon. 

dz expects the distance from the z coordinate of the current graphics 
position to the z coordinate of the next corner of the polygon. 

DESCRIPTION 

rpdr is the relative version of pdr. It specifies the next point in a filled 
polygon, using the previous point (the current graphics position) as the 
origin, rpdr updates the current graphics position. The next drawing 
routine will start drawing from that point. 
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SEE ALSO 

bgnpol, endpol, pclos, rpmv, v 

NOTES 

rpdr should not be used in new development. Rather, polygons should I 
be drawn using the high-performance v commands, surrounded by calls 
to bgnpol and endpol. Matrix commands pushma, transl, and popmat 
should be used to accomplish relative positioning. 

There can be no more than 256 vertices in a polygon. Therefore, there 
can be no more than 255 rpdr calls between rpmv and pclos. 



c 
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NAME 

rpmv, rpmvi, rpmvs, rpmv2, rpmv2i, rpmv2s - relative polygon 
move 

FORTRAN 77 SPECIFICATION 

subroutine rpmv(dx, dy, dz) 
real dx, dy, dz 

subroutine rpmvi(dx, dy, dz) 
integer*4 dx, dy, dz 

subroutine rpmvs(dx, dy, dz) 
integer*2 dx, dy, dz 

subroutine rpmv2(dx, dy) 
real dx, dy 

subroutine rpmv2i(dx, dy) 
integer*4 dx, dy 

subroutine rpmv2s(dx, dy) 
integer*2 dx, dy 

All of the above routines are functionally the same. They differ only in 
the type declarations of their parameters and in whether they assume a 
two-dimensional or three-dimensional space. 

PARAMETERS 

dx expects the distance from the x coordinate of the current graphics 
position to the x coordinate of the first point in a polygon. 

dy expects the distance from the y coordinate of the current graphics 
position to the y coordinate of the first point in a polygon. 

dz expects the distance from the z coordinate of the current graphics 
position to the z coordinate of the first point in a polygon. 

DESCRIPTION 

rpmv is the relative version of pmv. It specifies a relative move to the 
starting point of a filled polygon, using the current graphics position as 
the origin, rpmv updates the current graphics position to the new point. 
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Between rpmv and pclos, you can issue only the following Graphics 
Library subroutines: color, RGBcol, c, cpack, n, v, Imdef, and Imbind. 
Use Imdef and Imbind to respecify only materials and their properties. 

SEE ALSO 

bgnpol, endpol, pclos, rpdr, v 

NOTES 

rpmv should not be used in new development. Rather, polygons should 
be drawn using the high-performance v commands, surrounded by calls 
to bgnpol and endpol. Matrix commands pushma, transl, and popmat 
should be used to accomplish relative positioning. 

There can be no more than 256 vertices in a polygon. Therefore, there 
can be no more than 255 rpdr calls between rpmv and pclos. 



c 
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NAME 

sbox, sboxi, sboxs - draw a screen-aligned rectangle 

FORTRAN 77 SPECIFICATION 

subroutine sbox(xl, yl, x2, y2) 
real xl, yl, x2, y2 

subroutine sboxi(xl, yl, x2, y2) 
integer*4 xl, yl, x2, y2 

subroutine sboxs(xl, yl, x2, y2) 
integer*2 xl, yl, x2, y2 

All of the above functions are functionally the same except for the type 
declarations of the parameters. 

PARAMETERS 

xl expects the x coordinate of a corner of the box. 

yl expects the y coordinate of a corner of the box. 

x2 expects the x coordinate of the opposite corner of the box. 

y2 expects the y coordinate of the opposite corner of the box. 

DESCRIPTION 

sbox draws an unfilled, two-dimensional, screen-aligned rectangle. The 
rectangle is drawn as a sequence of four line segments, and therefore 
inherits many properties that affect the drawing of lines. These include 
the current color, writemask, line width, stipple pattern, and subpixel 
mode. The stipple pattern is initialized to bit zero of the current lines- 
tyle before the rectangle is drawn, then shifted continuously through the 
segments of the rectangle. 

The sides of the rectangle, will be parallel to the screen x and y axes. 
This rectangle cannot be rotated. The z coordinate is set to zero. 

When you use sbox, you must not use alpha blending, backfacing or 
frontfacing, depthcueing, fog, gouraud shading, lighting, line antialias- 
ing, screen subdivision, stenciling, texture mapping, or z-buffering. 
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sbox may be faster than rect on some machines. Use sbox when you 
need to draw a large number of screen-aligned rectangles. 

After sbox executes, the graphics position is undefined. 

SEE ALSO f 

backfa, bgnclo, blendf, deflin, depthc, linewi, linesm, lmbind, Isrepe, ^ 

rect, scrsub, setlin, shadem, stenci, subpix, texbin, zbuffer 



( 
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NAME 

sboxf, sboxfi, sboxfs - draw a filled screen-aligned rectangle 

FORTRAN 77 SPECIFICATION 

subroutine sboxf(xl, yl, x2, y2) 
real xl, yl, x2, y2 

subroutine sboxfi(xl, yl, x2, y2) 
integer*4 xl, yl, x2, y2 

subroutine sboxfs(xl, yl, x2, y2) 
integer*2 xl, yl, x2, y2 

All of the above functions are functionally the same except for the type 
declarations of the parameters. 

PARAMETERS 

xl expects the x coordinate of a corner of the filled box. 

yl expects the y coordinate of a corner of the filled filled box. 

x2 expects the x coordinate of the opposite corner of the filled box. 

y2 expects the y coordinate of the opposite corner of the filled box. 

DESCRIPTION 

sboxf draws a filled, two-dimensional, screen-aligned rectangle. The 
rectangle is drawn as a single polygon, and therefore inherits many pro- 
perties that affect the drawing of polygons. These include the current 
color, writemask, fill pattern, and subpixel mode. 

The sides of the rectangle will be parallel to the screen x and y axes. 
This rectangle cannot be rotated. The z coordinate is set to zero. 

When you use sboxf, you must not use alpha blending, backfacing or 
frontfacing, depthcueing, fog, gouraud shading, lighting, polygon 
antialiasing, screen subdivision, stenciling, texture mapping, or z- 
buffering. polymo must be set to PYMFIL. 



Version 3.0 - 1 - April 1990 



sboxf Graphics Reference, FORTRAN sboxf 

sboxf may be faster than rectf on some machines. Use sboxf when you 
need to draw a large number of screen-aligned rectangles. 

After sboxf executes, the graphics position is undefined. 

SEE ALSO r 

backfa, bgnpol, blendf, depthc, frontf, lmbind, polymo, polysm, rectf, ^ 

scrsub, setpat, shadem, stenci, subpix, texbin, zbuffe 



c 



c 
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NAME 

scale - scales and mirrors objects 

FORTRAN 77 SPECIFICATION 

subroutine scale(x, y, z) 
realx, y, z 

PARAMETERS 

x expects the scaling of the object in the x direction. 
y expects the scaling of the object in the y direction, 
z expects the scaling of the object in the z direction. 

DESCRIPTION 

scale shrinks, expands, and mirrors objects. Values with a magnitude 
greater than 1 expand the object; values with a magnitude less than 1 
shrink it. Negative values mirror the object. Mirroring places the 
reflection of an object in the area defined. The original is no longer 
displayed. 

scale is a modeling routine; it changes the current transformation 
matrix. All objects drawn after scale executes are affected. 

Use pushma and popmat to limit the scope of scale. 

SEE ALSO 

popmat, pushma, rotate, transl 
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NAME 

sclear - clear the stencil planes to a specified value 

FORTRAN SPECIFICATION 

subroutine sclear (sval) 
integer*4 sval 

PARAMETERS 

sval expects the integer value that is to be written to every stencil loca- 
tion 

DESCRIPTION 

sclear sets every pixel in the currently allocated stencil buffer (see 
stensi) to sval, the passed parameter. This clearing operation is limited 
by the current viewpo and scrnma, and is masked by the current swrite. 
Current color is unchanged. The polygon pattern, if any, is ignored. 

SEE ALSO 

stensi, swrite 

NOTES 

IRIS-4D G, GT, and GTX models, and the Personal Iris, do not support 
stenci, and therefore also do not support sclear. Use getgde to deter- 
mine whether stenci is supported. 

Because only the normal framebuffer includes stenci resources, sclear 
should be called only while draw mode is NORMAL. 



( 
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NAME 

scrbox - control the screen box 

FORTRAN SPECIFICATION 

subroutine scrbox(arg) 
integer*4 arg 

PARAMETERS 

arg Expects one of the symbolic constants: 

SBRESE: initialize screen box limits, (default) 

SBTRAC: track scan-converted geometry and characters and 
update the scrbox limits accordingly. 

SBHOLD: disable update of screen box limits; hold current 
values. 

DESCRIPTION 

scrbox is a dual of the scrmas capability. Rather than limiting drawing 
effects to a screen-aligned subregion of the viewport, it tracks the 
screen-aligned subregion (screen box) that has been affected. Unlike 
scrmas, which defaults to the viewport boundry if not explicitly 
enabled, scrbox must be explicitly turned on to be effective. 

While enabled (mode SBTRAC) scrbox maintains leftmost, rightmost, 
lowest, and highest window coordinates of all pixels that are scan con- 
verted. Because scrbox operates on the pixels that result from the scan 
conversion of points, lines, polygons, and characters; it correctly han- 
dles wide lines, antialiased (smooth) points and lines, and characters. 
Because scrbox operation may preceed the framebuffer, scan-converted 
pixels may update the screen box regardless of their Z compare, WID 
compare, or stencil compare results. 

scrbox results are guaranteed to bound the modified framebuffer region, 
but they may exceed the bounds of this region. 



Version 3.0 - 1 - April 1990 



scrbox Graphics Reference, FORTRAN scrbox 

When reset, the leftmost and lowest screen box values are set to be 
greater than the rightmost and highest values. 

SEE ALSO 

getscr, scrmas 

NOTES 

IRIS-4D G, GT, and GTX models, and the Personal Iris, do not support 
scrbox. Use getgde to determine whether scrbox is supported. 



( 



( 
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NAME 

screen - map world space to absolute screen coordinates 

FORTRAN SPECIFICATION 
subroutine screen 

PARAMETERS 

none 

DESCRIPTION 

screen sets the projection matrix and viewport of the current window so 
as to map world space to absolute screen coordinates (instead of to the 
more usual window-relative screen coordinates). This provides a con- 
venient coordinate system for operations that are not constrained to a 
window, e.g. reading pixels. 

screen is equivalent to: 

integer* 4 xmin, ymin 

call get org (xmin, ymin) 

call viewpo (-xmin, getgde (GDXPMA) -xmin, 
+ -ymin, getgde (GDYP MA) -ymin) 

call ortho2(-0.5, getgde (GDXPMA) +0 .5, 
+ -0.5, getgde (GDYPMA) +0.5) 

SEE ALSO 

fullsc, getgde, getori, viewpo, ortho2 

NOTE 

This routine is available only in immediate mode. 



Version 3.0 - 1 - April 1990 



scrmas Graphics Reference, FORTRAN scrmas 

NAME 

scrmas - defines a rectangular screen clipping mask 

FORTRAN 77 SPECIFICATION 

subroutine scrmas(left, right, bottom, top) 
integer*4 left, right, bottom, top 

PARAMETERS 

left expects the window coordinate of the left-most pixel column 
within the mask region. 

right expects the window coordinate of the right-most pixel column 
within the mask region. 

bottom expects the window coordinate of the lowest pixel row within 
the mask region. 

top expects the window coordinate of the highest pixel row within 
the mask region. 

DESCRIPTION 

scrmas defines a subregion of the current viewport that can be updated 
by drawing commands. Pixels outside this region cannot be modified by 
any drawing commands, including point, line, polygon, character, pixel 
write, and pixel copy commands. All pixel bitplane buffers, including 
color, depth, accumulation, and stencil buffers, are write protected. 
scrmas operates in all draw modes. 

The enabled subregion is specified as a screen-aligned rectangle in win- 
dow coordinates. Like viewpo, the boundary specification is inclusive, 
so the call scrmas(0,0,0,0) specifies a 1 -pixel rectangle in the lower-left 
corner of the window. 

When viewpo is called, the screen mask is set to match the newly 
specified viewport. Any previously scrmas specification is lost. 

scrmas must be specified entirely within the current viewport. 



c 



( 
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SEE ALSO 

drawmo, getscr, viewpo 

NOTE 

If you set left to be greater than right or bottom to be greater than top, all 
pixels in the viewport are write protected. 
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NAME 

scrnat - attaches the input focus to a screen 



integer*4 function scrnat(gsnr) f 



FORTRAN 77 SPECIFICATION 

integer*4 fund 
integer*4 gsnr 

PARAMETERS 

gsnr expects a screen number or the symbolic constant, INFOCU. 

FUNCTION RETURN VALUE 

The function returns the screen that previously had input focus, or -1 if 
there was an error (e.g., gsnr is not a valid screen number). 

DESCRIPTION 

scrnat attaches the input focus to the specified screen. It waits for any 
window manager or menu interaction to be completed before doing the 
attach. Calling scrnat with the argument INFOCU simply returns the / 
screen that currently has the input focus. V. 

On error, scrnat leaves the input focus unchanged. 

SEE ALSO 

getgde, getwsc, scrnse 

NOTES 

This routine is available only in immediate mode. 

Use getgde(GDNSCR) to determine the number of screens available to 
your program. Screens are numbered starting from zero. 
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NAME 

scrnse - selects the screen upon which new windows are placed 

FORTRAN 77 SPECIFICATION 

integer*4 function scrnse(gsnr) 
integer*4 gsnr 

PARAMETERS 

gsnr expects a screen number or the symbolic constant, EMFOCU, to 
select the screen with the input focus at the time the routine is 
called. 

FUNCTION RETURN VALUE 

The function returns the previously selected screen, or -1 if there was an 
error (e.g., gsnr is not a valid screen number). 

DESCRIPTION 

scrnse selects the screen upon which a subsequent winope, ginit, 
gbegin, creates a window. It also selects the screen to which getgde and 
gversi inquiries refer. The default is the screen with the input focus at 
the time the first Graphics Library routine is called. 

On error, scrnse leaves the currently selected screen unchanged. 

You can call scrnse prior to graphics initialization. 

SEE ALSO 

getgde, getwsc, ginit, gversi, winope, scrnat 

NOTES 

This routine is available only in immediate mode. 

Use getgde(GDNSCR) to determine the number of screens available to 
your program. Screens are numbered starting from zero. 
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NAME 

scrsub - subdivide lines and polygons to a screen-space limit 

FORTRAN SPECIFICATION 

subroutine scrsub(mode, params) | 

integer*4 mode 
real params() 

PARAMETERS 

mode Specify whether and how lines and polygons are to be subdi- 
vided. Options are: 

SSOFF: do not subdivide, (default) 

SSDEPT: subdivide based on z values in screen-coordinates. 

params Expects an array that contains parameter specifications for the 
subdivision mode that has been selected. 



SSOFF expects no values in the params array. 

SSDEPT expects three values in the params array: maxz, min- 
size, and maxsize, maxz specifies the distance, in screen- 
coordinates, between z- constant subdivision planes. (Z-buffer 
screen coordinates are defined by lsetde.) minsize and maxsize 
specify bounds, in units of pixels, of the screen size of the 
resulting subdivided polygons. Setting maxz to 0.0 eliminates 
screen-coordinate z from consideration during the subdivision. 
Likewise, setting minsize or maxsize to 0.0 eliminates lower or 
upper bounds on screen size from consideration. 



DESCRIPTION 



scrsub. 



c 



When scrsub mode is not SSOFF, lines and polygons are subdivided 
until the specified criteria are met. Parameters are assigned to created 
vertices as though they have been interpolated in eye-coordinates, rather 
than in screen-coordinates. Thus effects that result from (incorrect) 
linear interpolation in screen-coordinates can be compensated for with | 
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Mode SSDEPT slices polygons into strips whose edges have constant 
screen z value. It divides lines into segments whose endpoint z values 
differ by maxz. This subdivision is done after lighting, so the newly 
created vertices are not lighted, but rather simply take color values as 
linear interpolants of the original vertices (in eye-coordinates). Both fog 
and texture mapping are done after the depth subdivision, so both 
benefit from its operation. 

Polygon slices created by SSDEPT subdivision have edges whose z 
values differ by maxz. However, if the width of the resulting slices is 
less than minsize, the slices are increased to have width equal to minsize. 
For example, if maxsize is set to 0.0 (i.e. defeated), a polygon that 
directly faces the viewer is not subdivided, because all vertices have the 
same z value. As this polygon is rotated away from the viewer, it is 
sliced into strips whose edges are parallel to the axis of rotation. The 
number of strips increases as the rotation increases, until the strips reach 
a width (measured perpendicular to the axis of rotation) of minsize. At 
this angle the number of slices is at its maximum. As the rotation is 
continued, the slice width remains constant, and the number of slices 
decreases, reaching zero as the polygon becomes perpendicular to the 
viewer. 

When maxsize is non-zero, the description above changes only in that 
large polygons that are nearly perpendicular to the viewer are subdi- 
vided into strips of width maxsize. Likewise, lines segments created by 
SSDEPT subdivision are limited to a minimum length of minsize, and a 
maximum length of maxsize. 

SSDEPT subdivision improves the accuracy of texture mapping when 
non-orthographic projections are used, and improves the accuracy of fog 
calculations. It is not useful for lighting improvement. 

SEE ALSO 

fogver, texbin, tevbin 

NOTE 
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scrsub cannot be used while mmode is MSINGL. 

IRIS-4D G, GT, and GTX models, and the Personal Iris, do not support 
scrsub. 

BUGS 

When the screen size of subdivided polygons is limited, either by win- 
size or by maxsize, adjacent polygons can subdivide differently such that 
newly created vertices on their shared boundary do not coincide. In this 
case, some pixels at their shared boundary may not be scan converted by 
either polygon. 

Incorrect specification of either maxz or minsize can result in near- 
infinite polygon subdivision. To avoid the resulting poor graphics sys- 
tem response, IRIS-4D VGX models do not subdivide polygons whose 
SSDEPT subdivision would result in more than 2000 slices. 



( 



( 
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NAME 

setbel - sets the duration of the beep of the keyboard bell 

FORTRAN 77 SPECIFICATION 

subroutine setbel(durat) 
integer*4 durat 

PARAMETERS 

durat expects a value indicating the length of time the keyboad bell 
will sound. 

no beep. 

1 short beep. 

2 long beep. 

DESCRIPTION 

setbell sets the duration of the beep of the keyboard bell. The keyboard 
bell is activated by ringbe. 

SEE ALSO 

NOTE 

This routine is available only in immediate mode. 
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NAME 

setcur - sets the cursor characteristics 

FORTRAN 77 SPECIFICATION 

subroutine setcur(index, color, wtm) I 

integer*4 index, color, wtm ^ 

PARAMETERS 

index expects an index into the predefined definition table. 
color argument ignored. 
wtm argument ignored. 

DESCRIPTION 

setcur selects a cursor glyph from among those defined with defcur. 
color and wtm are ignored by this routine. To set the color for the cursor 
use mapcol and drawmo. 

SEE ALSO ( 

attach, cursty, defcur, curori, drawmo, getcur, mapcol, RGBcur 

NOTE 

This routine is available only in immediate mode. 



c 
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NAME 

setdbl - sets the lights on the dial and button box 

FORTRAN 77 SPECIFICATION 

subroutine setdbl(mask) 
integer*4 mask 

PARAMETERS 

mask expects 32 packed bits indicating which lights you want turned 
on. 

DESCRIPTION 

setdbl turns on a combination of the lights on the dial and switch box. 
A dial and switch box is an I/O device which has thirty-two lighted 
switches on it. Each bit in the mask corresponds to a light. For exam- 
ple, to turn on lights 4, 7, and 22 (and leave all the others off), set the 
mask to $400090. 

SEE ALSO 

dbtext 

NOTE 

This routine is available only in immediate mode. 
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NAME 

setdep - obsolete routine 

FORTRAN SPECIFICATION 

subroutine setdep(neai% far) | 

integer*! near, far ^ 

PARAMETERS 

near expects the screen coordinate of the near clipping plane. 
far expects the screen coordinate of the far clipping plane. 

DESCRIPTION 

This routine is obsolete. Although it continues to function to provide 
backwards compatibility, all new development should use its replace- 
ment, lsetde. 



SEE ALSO 

lsetde 



c 



c 
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NAME 

setlin - selects a linestyle pattern 

FORTRAN 77 SPECIFICATION 

subroutine setlin(index) 
integer*4 index 

PARAMETERS 

index expects an index into the linestyle table. 

DESCRIPTION 

setlin selects a linestyle pattern from a linestyle table defined by deflin. 
There is always a current linestyle; it draws lines and curves, and out- 
lines rectangles, polygons, circles, and arcs. The default linestyle is 0, 
which is a solid line. It cannot be redefined. 

SEE ALSO 

deflin, getlst, linewi 
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NAME 

setmap - selects one of the small color maps provided by multimap 
mode 

FORTRAN 77 SPECIFICATION 

subroutine setmap(mapnum) 
integer*4 mapnum 

PARAMETERS 

mapnum expects the number of the small color map to be used. 

DESCRIPTION 

setmap selects one of the small color maps provided by multimap 
mode. There are getgde(GBNMMA) maps, whose numbering starts 
from 0. setmap can only be used in multimap mode; it is ignored in 
onemapmode. 

SEE ALSO 

getgde, getmap, multim, onemap 

NOTE 

This routine is available only in immediate mode. 



c 
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NAME 

setmon - sets the monitor type 

FORTRAN 77 SPECIFICATION 

subroutine setmon(mtype) 
integer*4 mtype 

PARAMETERS 

mtype expects a symbolic constant that identifies the monitor mode to 
be used. There are five constants defined for this parameter: 

HZ30 selects 30Hz interlaced monitor mode. 

HZ30SG selects 30HZ noninterlaced with sync on green moni- 
tor mode. 

HZ60 selects 60Hz noninterlaced monitor mode. 

NTSC selects NTSC monitor mode. 

PAL selects PAL or SECAM monitor mode. 

STRJRECT puts your monitor in stereo viewing mode if it has 
that option. (Otherwise this is ignored.) 

DESCRIPTION 

setmon sets the monitor to 30Hz interlaced, 60Hz noninterlaced, 30Hz 
interlaced with sync on green, NTSC, or PAL, depending on whether 
mtype is HZ30, HZ60, HZ30SG, NTSC, or PAL, respectively. 

SEE ALSO 

getmon, getoth, setvid 

NOTES 

This routine is available only in immediate mode. 

The symbolic values for mtype mentioned above are defined in 
<gUfget.h>. 
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BUGS 



IRIS-4D VGX models may hang the graphics pipe, resulting in failure 
of all running programs including the window manager, when setmon is 
called while other graphics processes are running. 
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NAME 

setnur - sets a property for the display of trimmed NURBS surfaces 

FORTRAN 77 SPECIFICATION 

subroutine setnur 
integer*4 property 
real value 

PARAMETERS 

property expects the name of the property to be set. 

value expects the value to which the named property will be set. 

DESCRIPTION 

The display of NURBS surfaces can be controlled in different ways. 
The following is a list of the display properties that can be affected. 

NERRO: If value is 1.0, some error checking is enabled. If error 
checking is disabled, the system runs slightly faster. The 
default value is 0.0. 

NPIXEL: The value is the maximum length, in pixels, of edges of 
polygons on the screen used to render trimmed NURBS sur- 
faces. The default value is 50.0 pixels. 

SEE ALSO 

bgnsur, nurbss, bgntri, nurbsc, pwlcur, getnur 
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NAME 

setpat - selects a pattern for filling polygons and rectangles 

FORTRAN 77 SPECIFICATION 

subroutine setpat(index) 
integer *4 index 

PARAMETERS 

index expects the index into the table of defined patterns. 

DESCRIPTION 

setpat selects a pattern from a table of patterns previously defined by 
defpat The default pattern is pattern 0, which is solid. If you specify an 
undefined pattern, the default pattern is selected. 

SEE ALSO 

color, defpat, getpat, writem 



c 
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NAME 

setpup - sets the display characteristics of a given pop up menu entry 

FORTRAN 77 SPECIFICATION 

subroutine setpup(pup, entry, mode) 
integer*4 pup, entry, mode 

PARAMETERS 

pup expects the menu identifier of the menu whose entries you want 
to change. The menu identifier is the returned function value of 
the menu creation call to newpup. 

entry expects the position of the entry in the menu, indexed from 1 . 

mode expects a symbolic constant that indicates the display characteris- 
tics you want to apply to the chosen entry. For this parameter 
there are two defined symbolic constants: 

PUPNON, no special display characteristics, fully functional if 
selected. This is the default mode for newly created menu 
entries. 

PUPGRE, entry is greyed-out and disabled. Selecting a greyed- 
out entry has the same behavior as selecting the title bar. If the 
greyed-out entry has a submenu associated with it, that submenu 
does not display. 

DESCRIPTION 

Use setpup to alter the display characteristics of a pop up menu entry. 
Currently, you use this routine to disable and grey-out a menu entry. 

EXAMPLE 

Here is an example that disables a single entry: 

menu = newpup ( ) 

call addtop (menu, 'menu %t litem 1 litem 2 litem 3 litem 4' , 39, 

call setpup (menu, 1, PUPGRE) 
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Subsequent calls of dopup(menu) would display the menu with the 
menu entry labeled "item 1" is greyed out, and never gets a return 
value of 1. 

SEE ALSO 

dopup, freepu, newpup 

NOTE 

This routine is available only in immediate mode. 



( 
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NAME 

setsha - obsolete routine 

FORTRAN 77 SPECIFICATION 

subroutine setsha(shade) 
integer*4 shade 

PARAMETERS 

none 

DESCRIPTION 

This routine is obsolete. Although it continues to function to provide 
backwards compatibility, all new development should use its identical 
replacement, color. 

SEE ALSO 

color 
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NAME 

setval - assigns an initial value and a range to a valuator 

FORTRAN 77 SPECIFICATION 

subroutine setval(v ? init, vmin, vmax) | 

integer*4 v, init, vmin, vmax ^ 

PARAMETERS 

v expects the device number for the valuator being set. 

init expects the initial value to be assigned to the valuator. 

vrnin expects the minimum value that the device can assume. 

vmax expects the maximum value that the device can assume. 

DESCRIPTION 

setval sets the initial value and the minimum and maximum values the 
specified device can assume. All arguments are 16-bit values. 

Some devices, such as tablets, report values fixed to a grid. In this case, | 
the device defines an initial position and init is ignored. ^ 

SEE ALSO 

getval 

NOTE 

This routine is available only in immediate mode. 



( 



Version 3.0 - 1 - April 1990 



setvid Graphics Reference, FORTRAN setvid 

NAME 

setvid, getvid - set and get video hardware registers 

FORTRAN 77 SPECIFICATION 

subroutine setvid(reg, value) 
integer*4 reg, value 

integer*4 function getvid(reg) 
integer*4 reg 

PARAMETERS 

reg expects the name of the register to access. 
value expects the value which is to be placed into reg. 

FUNCTION RETURN VALUE 

The returned value of getvid is the value read from register reg, or -1. 
-1 indicates that reg is not a valid register or that you queried a video 
register on a system without that particular board installed. 

DESCRIPTION 

setvid sets the specified video hardware register to the specified value. 
getvid returns the value of the specified video hardware register. 
Several different video boards are supported; the board names and regis- 
ter identifiers are listed below. 

Display Engine Board 
DE_R1 

CG2 Composite Video and Genlock Board 
CG_CONTROL 
CG_CPHASE 
CG_HPHASE 
CG MODE 
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VP1 Live Video Digitizer Board 
VP_ALPHA 
VP_BRITE 

VP_CMD 

VP_CONT f- 

VP_DIGVAL I 

VP_FBXORG 

VP_FBYORG 

VP.FGMODE 

VP.GBXORG 

VP_GBYORG 

VP_HBLANK 

VP_HEIGHT 

VP_HUE 

VP.MAPADD 

VP_MAPBLUE 

VP_MAPGREEN 

VP_MAPRED 

VP_MAPSRC 

VP_MAPSTROBE 

VP_PIXCNT f 

VP_SAT V 

VP_STATUSO 

VP_STATUS1 

VP_VBLANK 

VP_WIDTH 

SEE ALSO 

getmon, getoth, setmon, videoc 

NOTES 

These routines are available only in immediate mode. 

The DE_R1 register is actually present only on the video board used in 
the IRIS-4D B, G, GT, and GTX models. It is emulated on all other 
models. I 
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The Live Video Digitizer is available as an option for IRIS-4D GTX 
models only. 

For C, the symbolic constants named above are defined in the files 
<gllcg2vme.h> and <gl/vpl.h> . You will need to create your own ver- 
sions of them for FORTRAN 77. 
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NAME 

shadem - selects the shading model 

FORTRAN 77 SPECIFICATION 

subroutine shadem(model) 
integer*4 model 

PARAMETERS 

model expects one of two possible flags: 

FLAT, tells the system to assign the same color to each pixel of 
lines and polygons during scan conversion. 

GOURAU, tells the system to interpolate color from vertex to 
vertex when scan converting lines, and to interpolate color 
throughout the area of filled polygons when they are scan con- 
verted. This is the default shading model. 

DESCRIPTION 

shadem determines the shading model that the system uses to render 
lines and filled polygons. When the system uses Gouraud shading, the 
colors along a line segment are an interpolation of the colors at its ver- 
tices, and the colors in the interior of a filled polygon are an interpola- 
tion of the colors at its vertices. Currently the interpolation is linear. 
Future architectures may do nonlinear interpolation to compensate for 
errors due to extreme projection. 

When flat shading is specified, color is not interpolated. Rather, the 
color of the second vertex of a line segment, or of the last vertex of a 
polygon, is used at each pixel of the line segment or polygon. Thus con- 
nected lines, triangles, and quadrilaterals can be successfully flat shaded. 
For example, the color of the nth segment in a connected line is deter- 
mined by the color of vertex n+1, and the color of the nth triangle in a 
mesh is determined by the color of vertex n+2. 

Color intepolation or flat shading occurs after lighting and depthcueing 
calculations are made, so both these color generation operations can be 
either flat or Gouraud shaded. Texture, fog, and blending calculations, 
however, occur after pixel shading is completed. These operations are 
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always themselves Gouraud shaded, regardless of the current shade 
model. This means, for example, that a triangle mesh can be lighted or 
depthcued with flat shaded facets, then fogged or texture mapped 
smoothly. 

SEE ALSO 
getsm 



NOTE 



Gouraud is the default shading model, but is in general slower than flat 
shading. To improve performance, specify flat shading where Gouraud 
shading is not required. 



BUGS 



On IRIS-4D B and G models, and on the Personal Iris without Turbo 
Graphics, lines are always drawn with constant color regardless of the 
current shading model. Also, flat shaded independent polygons scan 
convert to a single color, but this color is not always that of the last ver- 
tex specified. Rat shaded polygons yeild consistent results on these 
models only when the same color is specified at each vertex. 

On IRIS-4D GT and GTX models, lines drawn with move and draw are 
always flat shaded, and lines drawn with v commands are always 
Gouraud shaded, regardless of the current shading model. Independent 
polygons are always Gouraud shaded. Triangle meshes are correctly flat 
or Gouraud shaded, depending on the shading model. 
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NAME 

shader - obsolete routine 

FORTRAN 77 SPECIFICATION 

subroutine shader(lowin, highin, zl, z2) ■ 

integer*! lowin, highin, zl, z2 

PARAMETERS 

lowin expects the low-intensity color map index. 

highin expects the high-intensity color map index. 

zl expects the low z value to be mapped to. 

z2 expects the high z value to be mapped to. 

DESCRIPTION 

This routine is obsolete. Although it continues to function to provide 
backwards compatibility, all new development should use its replace- 
ment, Ishade. f 

SEE ALSO 

Ishade 



( 
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NAME 

single - writes and displays all bitplanes 

FORTRAN 77 SPECIFICATION 
subroutine single 

PARAMETERS 

none 

DESCRIPTION 

single invokes single buffer mode. In single buffer mode, the system 
simultaneously updates and displays the image data in the active bit- 
planes. Consequently, incomplete or changing pictures can appear on 
the screen, single does not take effect until gconfi is called. 

SEE ALSO 

cmode, double, gconfi, getdis, gsync, RGBmod 

NOTE 

This routine is available only in immediate mode. 
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NAME 

smooth - obsolete routine 

FORTRAN 77 SPECIFICATION 

subroutine smooth(mode) 
integer*4 mode 

PARAMETERS 

mode expects 1 to turn on antialiasing or to turn it off. 

DESCRIPTION 

This routine is obsolete. Although it continues to function to provide 
backwards compatibility, all new development should use its identical 
replacement, linesm. 

SEE ALSO 

linesm 



c 
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NAME 

spclos - obsolete routine 

FORTRAN 77 SPECIFICATION 
subroutine spclos 

PARAMETERS 

none 

DESCRIPTION 

This routine is obsolete. Since setting of shadem determines if a 
polygon is shaded, spclos simply functions as pclos. All new develop- 
ment should use pclos. 

SEE ALSO 

pclose, shadem 
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NAME 

splf, splfi, splfs, splf2, splf2i, splf2s - draws a shaded filled polygon 

FORTRAN 77 SPECIFICATION 

subroutine splf(n, parray, iarray) I 

integer*4 n 
real parray(3,n) 
integer*2 iarray(n) 

subroutine splfi(n, parray, iarray) 
integer*4 n 
integer*4 parray(3,n) 
integer*2 iarray(n) 

subroutine splfs(n, parray, iarray) 
integer*4 n 
integer*2 parray(3,n) 
integer*2 iarray(n) 

subroutine splf2(n, parray, iarray) 

integer*4 n ^ 

real parray(2,n) f 

integer*2 iarray(n) 

subroutine splf2i(n, parray, iarray) 
integer*4 n 
integer*4 parray(2,n) 
integer*2 iarray(n) 

subroutine splf2s(n, parray, iarray) 
integer*4 n 
integer*2 parray(2,n) 
integer*2 iarray(n) 

All of the above routines are functionally the same. They differ only in 
the type declarations of their parameters and in whether they assume a 
two- or three-dimensional space. 



( 
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PARAMETERS 

n expects the number of vertices in the polygon. There can be no 

more than 256 vertices in a single polygon. 

parr ay expects an array containing the vertices of a polygon. 

iarray expects the array containing the color map indices which deter- 
mine the intensities of the vertices of the polygon 

DESCRIPTION 

splf draws Gouraud-shaded polygons using the current pattern and wri- 
temask. Polygons are represented as arrays of points. The first and last 
points automatically connect to close a polygon. After the polygon is 
drawn, the current graphics position is set to the first point in the array. 
splf must be used in color map mode. 

SEE ALSO 

cmode, concav, poly, rect, rectf, pdr, pmv, rpdr, rpmv 
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NAME 

stenci - alter the operating parameters of the stencil 

FORTRAN SPECIFICATION 

subroutine stenci(enable, ref, func, mask, fail, pass, zpass) 
integer*4 enable, ref, func, mask, fail, pass, zpass 

PARAMETERS 

enable expects either .TRUE, or .FALSE., enabling or disabling sten- 
cil operation. When stencil operation is disabled (the default), 
the values of the subsequent six parameters are ignored, 

ref expects a reference value used by the stencil compare function. 

func expects one of eight flags specifying the stencil comparison 
function. These flags are SFNEVE, SFLESS, SFEQUA, 
SFLEQU, SFGREA, SFNOTE, SFGEQU, and SFALWA. 

mask expects a mask specifying which stencil bitplanes are 
significant during the comparison operation. 

fail expects one of six flags indicating which stencil operation 
should be performed should the stencil test fail. The values are 
STKEEP, STZERO, STREPL, STINCR, STDECR, and 

STINVE. 

pass expects one of six flags indicating which stencil operation 
should be performed should the stencil test pass, and the z- 
buffer test (if z-buffering is enabled) fail. The values are 
STKEEP, STZERO, STREPL, STINCR, STDECR, and 

STINVE. 

zpass expects one of six flags indicating which stencil operation 
should be performed should the stencil and z-buffer tests pass. 
Its value is not significant when the z-buffer is not enabled. The 
values are STKEEP, STZERO, STREPL, STINCR, 
STDECR, and STINVE. 



( 
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DESCRIPTION 

stenci operates as a superior z-buffer test with a different algorithm. 
When stenci is enabled, each pixel write first tests the stencil bitplanes. 
Both the color and z-buffer bitplane writes, as well as the write of the 
stencil bitplanes, are conditioned by the stencil test, stenci operation can 
be enabled only if stencil bitplanes are present (see stensi). Stencil bit- 
planes are present only in the normal framebuffer, so stenci should be 
called only while draw mode is NORMAL. 

When the z-buffer is enabled, three test cases are distinguished: 

fail Stencil test fails. 

pass Stencil test passes, but z-buffer test fails. 

zpass Stencil test passes, and z-buffer test passes. 

(When the z-buffer is not enabled, only cases fail and pass are con- 
sidered.) In all three cases the stencil bitplanes are updated with a 
potentially new value. This value is a function of the case. The user 
specifies, for each case, which of six possible values will be used: 

STKEEP Keep the current value (no change). 

STZERO Replace with zero. 

STREPL Replace with the reference value. 

STINCR Increment by one (clamp to max). 

STDECR Decrement by one (clamp to zero). 

STINVE Invert all bits. 

Arguments fail, pass, and zpass are each specified as one of STKEEP, 
STZERO, STREPL, STINCR, STDECR, and STINVE. 

ref is the reference value used by the function that determines whether 
the stencil test passes or fails, func specifies the comparison between ref 
and the current stencil plane value. This comparison function is 
specified with the flags: 

SFNEVE Never pass. 

SFLESS Pass if ref is less than stencil. 
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SFLEQU Pass if ref is less than or equal to stencil. 

SFEQUA Pass if ref is equal to stencil 

SFGRE A Pass if ref is greater than stencil 

SFGEQU Pass if ref is greater than or equal to stencil 

SFNOTE Pass if ref is not equal to stencil 

SFALWA Always pass. 

The stencil bitplanes are treated as an unsigned integer of planes bits, 
where planes is the value passed to stensi to allocate the stencil buffer. 

mask is a field that specifies which stencil bitplanes are to be considered 
by the test. It does not affect which bitplanes are updated. 

If the z-buffer is enabled, color and depth fields are drawn only in the 
zpass case (both the stencil and depth tests pass). If the z-buffer is not 
enabled, color is drawn only in the pass case. The zpass case is ignored. 

SEE ALSO 

drawmo, polymo, sclear, stensi, swrite, zbuffe 

NOTES 

IRIS-4D G, GT, and GTX models, and the Personal Iris, do not support 
stenci. Use getgde to determine whether stenci is supported. 

stenci is supported only in the normal framebuffer, and is therefore 
effective only while draw mode is NORMALW. 



BUGS 



IRIS-4D VGX models do not support stencil operation when afunct is 
enabled. 



c 
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NAME 

stensi - specify the number of bitplanes to be used as stencil planes 

FORTRAN SPECIFICATION 

subroutine stensi(planes) 
integer*4 planes 

PARAMETERS 

planes number of bitplanes to be allocated as stencil planes. Only 
values through 8 are accepted. The default is 0. 

DESCRIPTION 

stensi specifies an alternate configuration of the normal framebuffer in 
which some bitplanes are used as a stencil, planes specifies the number 
of bitplanes to be used for stenciling. The constraints on planes, as well 
as the relationship of the stencil bitplanes to the other normal bitplanes, 
are machine dependent. Call getgde(GDBIST) to determine how many 
bitplanes are available for stencil operation. 

stensi takes effect only after gconfi has been called. Because stencil bit- 
planes are available only in the normal framebuffer, stensi should be 
called only while draw mode is NORMAL. 

SEE ALSO 

drawmo, gconfi, stenci 

NOTES 

This routine is available only in immediate mode. 

IRIS-4D B, G, GT, and GTX models, and the Personal Iris, do not sup- 
port stensi. 



BUGS 



IRIS-4D VGX machines without the optional alpha bitplanes allocate 
stencil bitplanes from the least-significant z-buffer bitplanes. Z-buffer 
operation compensates for this allocation automatically, so the 
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programmer is aware of the allocation only when z-buffer contents are 
read back using lrectr. Use getgde to determine whether your machine 
has alpha bitplanes. 



( 
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NAME 

stepun - specifies that a graphics window change size in discrete steps 

FORTRAN 77 SPECIFICATION 

subroutine stepun(xunit, yunit) 
integer*4 xunit, yunit 

PARAMETERS 

xunit expects the amount of change per unit in the x direction. The 
amount is measured in pixels. 

yunit expects the amount of change per unit in the y direction. The 
amount is measured in pixels. 

DESCRIPTION 

stepun specifies the size of the change in a graphics window in discrete 
steps of xunit and yunit. Call stepun at the beginning of a graphics pro- 
gram; it takes effect when you call winope. stepunit resizes graphics 
windows in units of a standard size (in pixels). If winope is not called, 
stepun is ignored. 

SEE ALSO 

winope, fudge 

NOTE 

This routine is available only in immediate mode. 
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NAME 

strwid - returns the width of the specified text string 

FORTRAN 77 SPECIFICATION 

integer*4 function strwid(str, length) | 

character*(*) str ^ 

integer*4 length 

PARAMETERS 

str expects the name of the string that is to be measured. 

length expects the number of characters in the string that is to be meas- 
ured. 

DESCRIPTION 

strwid returns the width of a text string in pixels, using the character 
spacing parameters of the current raster font, strwid is useful when you 
do a simple mapping from screen space to world space. 

Undefined characters have zero width. I 

SEE ALSO 

getlwi, mapw, mapw2 

NOTE 

This routine is available only in immediate mode. 



c 
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NAME 

subpix - controls the placement of point, line, and polygon vertices 

FORTRAN 77 SPECIFICATION 

subroutine subpix(b) 
logical b 

PARAMETERS 

h expects either .FALSE, or .TRUE.. 

.FALSE, forces screen vertices to the centers of pixels (default). 
.TRUE, positions screen vertices exactly. 

DESCRIPTION 

subpix controls the placement of point, line, and polygon vertices in 
screen coordinates. By default subpix is .FALSE., causing vertices to 
be snapped to the center of the nearest pixel after they have been 
transformed to screen coordinates. Vertex snapping introduces artifacts 
into the scan conversion of lines and polygons. It is especially noticable 
when points or lines are drawn smooth (see pntsmo and linesm). Thus 
subpix is typically set to .TRUE, while smooth points or smooth lines 
are being drawn. 

In addition to its effect on vertex position, subpix also modifies the scan 
conversion of lines. Specifically, non-subpixel positioned lines are 
drawn closed, meaning that connected line segments both draw the pixel 
at their shared vertex, while subpixel positioned lines are drawn half 
open, meaning that connected lines segments share no pixels. (Smooth 
lines are always drawn half open, regardless of state of subpix.) Thus 
subpixel positioned lines produce better results when logico or blendf 
are used, but will produce different, possibly undesirable results in 2-D 
applications where the endpoints of lines have been carefully placed. 

For example, using the standard 2-D projection: 

call ortho2 (left-0 . 5 , right+0 . 5 , bottom-0 . 5 , top+0 . 5 ) 
call v i e wpo ( left , right , bottom , top ) 
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subpixel positioned lines match non-subpixel positioned lines pixel for 
pixel, except that they omit either the right-most or top-most pixel. 
Thus the non-subpixel positioned line drawn from (0,0) to (0,2) fills pix- 
els (0,0), (0,1), and (0,2), while the subpixel positioned line drawn 
between the same coordinates fills only pixels (0,0) and (0,1). 

SEE ALSO 

linesm, pntsmo 

NOTES 

This routine does not function on IRIS-4D B or G models. 

The ERIS-4D GT and GTX models do not implement subpixel posi- 
tioned polygons. They also do not implement subpixel positioned non- 
smooth lines. 

On the Personal Iris polygons are always subpixel positioned, regardless 
of the value of subpix. Subpixel positioned non-smooth lines are not 
implemented. 



c 
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NAME 

swapbu - exchanges the front and back buffers of the normal frame- 
buffer 

FORTRAN SPECIFICATION 
subroutine swapbu 

PARAMETERS 
none 

DESCRIPTION 

swapbu causes the front and back buffers of the normal firamebuffer to 
be exchanged during the next vertical retrace period. Once an image is 
fully drawn in the back buffer, swapbu displays it. swapbu is ignored 
when the normal firamebuffer is in single buffer mode. It has no effect 
on the overlay, underlay, or popup framebuffers, regardless of the 
current draw mode. 

To swap overlay or underlay buffers, or to swap buffers in more than 
one firamebuffer simultaneously, you must use mswapb. 

SEE ALSO 

double, drawmo, mswapb, swapin 
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NAME 

swapin - defines a minimum time between buffer swaps 

FORTRAN 77 SPECIFICATION 

subroutine swapin(i) 
integer*4 i 

PARAMETERS 

i expects the number of retraces to wait before swapping the front and 
back buffers. The default interval is 1. 

DESCRIPTION 

swapin defines a minimum number of retraces between buffer swaps. 
For example, for a swap interval of 5, the system refreshes the screen at 
least five times between successive buffer swaps, swapin changes 
frames at a steady rate if a new image can be created within one swap 
interval. 

Like the swapbu and mswapb commands that it affects, swapin is 
ignored by framebuffers in single buffer mode. 

A single swap interval counter is shared by the normal, overlay, and 
underlay framebuffers. The interval is enforced between all buffer swap 
requests, regardless of which framebuffers are swapped. 

SEE ALSO 

double, drawmo, mswapb, swapbu 

NOTE 

This routine is available only in immediate mode. 



( 
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NAME 

swaptm - toggles the triangle mesh register pointer 

FORTRAN 77 SPECIFICATION 
subroutine swaptm 

PARAMETERS 

none 

DESCRIPTION 

The triangle mesh hardware stores two vertices. After each new vertex 
is specified (and a triangle comprising the new vertex and the two stored 
vertices is drawn), one of the stored vertices is replaced by the new ver- 
tex. The value of a two-value pointer determines which vertex is 
replaced. This pointer is toggled after each vertex, causing alternate 
stored vertices to be replaced, swaptm toggles the pointer without 
specification of a new vertex (and no triangle is drawn). 

SEE ALSO 

bgntme, v 



NOTE 



Operation is undefined if swaptm is called before the second vertex of a 
triangle mesh is specified. 
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NAME 

swinop - creates a graphics subwindow 

FORTRAN SPECIFICATION 

integer*4 function swinop(parent) 
integer*4 parent 

PARAMETERS 

parent expects the GID (graphics window identifier) of the window (or 
subwindow) in which you want to open a subwindow. The GID 
is the returned function value of a previous call to either 
swinop or winope. 

FUNCTION RETURN VALUE 

The returned value of this function is either a -1 or the graphics window 
identifier for the subwindow just created. Use this value to identify this 
subwindow to other graphics routines. 

A returned function value of -1 indicates that the system cannot create 
any more graphics windows. 

DESCRIPTION 

swinop creates a graphics subwindow. The graphics state of the new 
subwindow is initialized to its defaults (see greset) and it becomes the 
current window. 

Subwindows have no window borders or window manager function but- 
tons. Window constraints do not apply to subwindows. A subwindow 
is repositioned automatically when its parent is moved, so that its origin 
with respect to the parent's origin remains constant. Resizing the parent 
does not automatically resize a subwindow, but keeps the distance 
between the upper left hand corners constant. Imaging in a subwindow 
is limited (clipped) to the area of the parent window. 

After calling swinop, the application must call winpos to specify the 
location of die subwindow' s boundaries with respect to the origin of its 
parent window. 
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If parent is the GID of a subwindow, the parent of that subwindow 
becomes the parent of the new subwindow for the purpose of position- 
ing the subwindow. 

When using the DGL (Distributed Graphics Library), the graphics win- 
dow identifier also identifies the graphics server associated with the win- 
dow. 

swinop queues the pseudo devices INPTCH and REDRAW. 

SEE ALSO 

greset, winclo, winget, winope, winpos, winset 
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NAME 

swrite - specify which stencil bits can be written 

FORTRAN SPECIFICATION 

subroutine swrite(mask) 
integer*4 mask 

PARAMETERS 

mask expects a mask whose least-significant bits are used to control 
writing of the stencil bitplanes. Bitplanes corresponding to l's in 
the mask can be written, those corresponding to O's are read- 
only. 

DESCRIPTION 

swrite specifies which of the stencil bitplanes are written both during 
normal stencil operation and stencil clear (see sclear). Bits through 
planes A are significant, where planes is the current size of the stencil 
buffer. 

Because only the normal framebuffer includes stencil bitplanes, swrite 
should be called only while draw mode is NORMAL. 

SEE ALSO 

drawmo, sclear, stenci, stensi 

NOTES 

IRIS-4D G, GT, and GTX models, and the Personal Iris, do not support 
stencil bitplanes, and therefore do not support swrite. Use getgde to 
determine whether stencil bitplanes are supported. 



( 
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NAME 

t2d, t2f, t2i, t2s - specify a texture coordinate 

FORTRAN SPECIFICATION 

subroutine t2s(vector) 
integer*2 vector(2) 

subroutine t2i(vector) 
integer*4 vector(2) 

subroutine t2f(vector) 
real vector(2) 

subroutine t2d(vector) 
double vector(2) 

PARAMETERS 

vector expects a 2-element array containing s and t texture coordinates. 
Put the s coordinate in element 1 of the array, and the t coordi- 
nate in element 2. 

DESCRIPTION 

t sets the current texture coordinates, s and t. The specified texture coor- 
dinates remain valid until they are replaced. All draw modes share the 
same texture coordinates. 

Using texgen it is possible for one or both of the texture coordinates to * 
be replaced by a graphics system generated value. The coordinate or 
coordinates that are not being replaced continue to be specified by t. 

Both s and t are transformed, prior to use, by the Texture matrix, which 
is modified while mmode is MTEXTU. 

Texture coordinates are ignored while texture mapping is not enabled. 

SEE ALSO 

mmode, texgen, texdef, texbin, tevdef, tevbin 
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NOTES 



IRIS-4D G, GT, and GTX models, and the Personal Iris, do not support 
texture mapping, t is ignored by these machines. Use getgde to deter- 
mine whether texture mapping is supported. 

t cannot be used while mmode is MSINGL. I ) 



c 
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NAME 

tevbin - selects a texture environment 

FORTRAN SPECIFICATION 

subroutine tevbin(target, index) 
integer*4 target, index 

PARAMETERS 

target expects the texture resource to which the environment definition 
is to be bound. There is only one appropriate resource, 
TVENVO. 

index expects the name of the texture environment that is being bound. 
Name is the index passed to tevdef when the environment was 
defined. 

DESCRIPTION 

tevbin specifies which of the previously defined texture mapping 
environments is to be the current environment. The texture environment 
defines how the results of the texture function are applied. Texture 
environments are defined using tevdef. 

By default environment definition is bound to TVENVO. Texture 
mapping is enabled when an environment definition other than is 
bound to TVENVO, and a texture definition other than is bound to 
TXTEXT. (Seetexbin.) 

SEE ALSO 

t, tevdef, texdef, texbin 

NOTES 

DRIS-4D G, GT, and GTX models, and the Personal Iris, do not support 
texture mapping, tevbin is ignored by these machines. Use getgde to 
determine whether texture mapping is supported. 
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tevbin cannot be used while mmode is MSINGL. 
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NAME 

tevdef - defines a texture mapping environment 

FORTRAN SPECIFICATION 

subroutine tevdef(index, np, props) 
integer*4 index, np 
realpropsO 

PARAMETERS 

index expects the name of the environment being defined. Index is 
reserved as a null definition, and cannot be redefined. 

np expects the number of symbols and floating point values in 
props, including the termination symbol TVNULL. If np is 
zero, it is ignored. Operation over network connections is more 
efficient when np is correctly specified, however. 

props expects the array of floating point symbols and values that define 
the texture environment, props must contain a sequence of sym- 
bols, each followed by the appropriate number of floating point 
values. The last symbol must be TVNULL, which is itself not 
followed by any values. 

DESCRIPTION 

Evaluation of the texture function at a pixel yields 1, 2, 3, or 4 values, 
depending on the value of nc passed to texdef when the currently bound 
texture was defined. Texture environment determines how these texture 
values are used, not how they are computed or filtered, tevdef defines 
an environment based on options specified in the props array. If no 
options are specified, a reasonable default environment is defined. 

Before the options can be defined, several conventions must be esta- 
blished: 

1. The color components of the incoming pixel (prior to texture map- 
ping) are refered to as Rin, Gin, Bin, and Ain. 
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2. The components of the texture function (computed at each pixel) are 
refered to as I, R, G, B, and A, depending on the number of com- 
ponents in the currently bound texture. For example, the single 
value of a 1 -component texture function is refered to as I, while the 
four components of a 4-component texture are refered to as A (value 
0), B (value 1), G (value 2), and R (value 3). Refer to the texdef 
manual page for an explanation of how texture function values 
correspond to the image pixels used to define the texture. 

0123 (texture function value) 
1 -component texture I 
2-component texture AI 
3-component texture BGR 
4-component texture ABGR 

3. The components of the outgoing color that results from application 
of the texture function to the incoming pixel color, based on the tex- 
ture environment, are Rout, Gout, Bout, and Aout. 

Texture environment options are specified as a list of symbols, each fol- 
lowed by the appropriate number of floating point values, in the props 
array. The last symbol must be TVNULL. 

TVMODU is the default texture environment. It specifies an 
environment in which incoming color components are multiplied by 
texture values. No floating point values follow this token. The 
exact arithmetic for 1, 2, 3, and 4 component texture functions is: 

1 -component : Rout=Rin* I , Gout=Gin*I , Bout=Bin* I , Aout=Ain 
2-component : Rout=Rin*I, Gout=Gin*I,Bout=Bin*I, Aout=Ain*A 
3-component : Rout=Rin*R, Gout=Gin*G,Bout : =Bin*B, Aout=Ain 
4-component : RoutHRin*R, Gout=Gin*G, Bout=Bin*B, Aout=Ain*A 

TVBLEN specifies a texture environment in which texture function 
values are used to blend between the incoming color and the current 
texture environment color constant: (Rcon,Gcon,Bcon,Acon). No ^ 
floating point values follow this token. Only 1 and 2 component I 
texture functions have defined behavior when this environment is 
specified. The exact arithmetic for these texture functions is: 
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1 -component: Rout = Rin* (1-1) + Rcon*I 

Gout = Gin*(l-I) + Gcon*I 

Bout « Bin*(l-I) + Bcon*I 

Aout = Ain 
2 -component : Rout = Rin* (1-1) + Rcon*I 

Gout = Gin*(l-I) + Gcon*I 

Bout = Bin*(l-I) + Bcon*I 

Aout = Ain*A 
3 -component : undefined 
4 -component: undefined 

TVDEC A specifies a texture environment in which texture function 
alpha is used to blend between the incoming color and the texture 
function color. No floating point values follow this token. Only 3 
and 4-component texture functions have defined behavior when this 
environment is specified. Note that the 3-component version simply 
outputs the texture colors, because no alpha texture component is 
available for blending. The exact arithmetic is: 

l-component: undefined 
2 -component: undefined 
3-component : Rout = R 

Gout = G 

Bout = B 

Aout = Ain 
4-component: Rout = Rin* (1-A) + R*A 

Gout = Gin* (1-A) + G*A 

Bout = Bin* (1-A) + B*A 

Aout = Ain 

TVCOLO specifies the constant color used by the TVBLEN 
environment. Four floating point values, in the range 0.0 through 
1.0, must follow this symbol. These values specify Rcon, Gcon, 
Bcon, and Aeon. By default, all are set to 1.0. 
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Symbols TVMODU, TVBLEN, and TVDECA are exclusive; only one 
should be included in the props array. If none are included, TVMODU 
is chosen by default. 

The texture environment is used to apply the results of the texture func- 
tion to pixel color data after shading, but before fog is blended. Condi- 
tional pixel writes based on pixel alpha are computed after texture and 
fog are applied. (See afunct.) This allows texture transparency to con- 
trol the conditional writing of pixels. 

Each time an index is passed to tevdef, the definition corresponding to 
that index is completely respecified. Do not attempt to change a portion 
of a texture environment definition. 

SEE ALSO 

afunct, scrsub, t, tevbin, texbin, texdef , texgen 

NOTES 

DRIS-4D G, GT, and GTX models, and the Personal Iris, do not support 
texture mapping, tevdef is ignored by these machines. Use getgde to 
determine whether texture mapping is supported. 

IRIS-4D VGX models without alpha bitplanes do not fully support 4- 
component textures. When a 4-component texture is used, it is treated 
by the texture environment as though it were a 3-component texture. 
Use getgde(GDBNSA) to determine whether alpha bitplanes are avail- 
able. 



BUGS 



IRIS-4D VGX models do not support simultaneous texture mapping and 
polygon antialiasing. (See polysm.) 
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NAME 

texbin - selects a texture function 

FORTRAN SPECIFICATION 

subroutine texbin(target, index) 
integer*4 target, index 

PARAMETERS 

target expects the texture resource to which the texture function 
definition is to be bound. There is only one appropriate 
resource, TXTEXT. 

index expects the name of the texture function that is being bound. 
Name is the index passed to texdef when the texture function 
was defined. 

DESCRIPTION , 

texbin specifies which of the previously defined texture mapping func- 
tions is to be the current texture function. The texture function defines 
how texture coordinates s and t are converted into a 1, 2, 3, or 4 value 
result. Texture functions are defined using texdef. 

By default texture function definition is bound to TXTEXT. Texture 
mapping is enabled when an texture function definition other than is 
bound to TXTEXT, and a texture environment definition other than is 
bound to TVENVO. (See tevbin.) 

SEE ALSO 

t, tevbind, tevdef, texdef 

NOTES 

IRIS-4D G, GT, and GTX models, and the Personal Iris, do not support 
texture mapping, texbin is ignored by these machines. Use getgde to 
determine whether texture mapping is supported. 
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texbin cannot be used while mmode is MSINGL. 
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NAME 

texdef - convert a 2-dimensional image into a texture 

FORTRAN SPECIFICATION 

subroutine texdf2(index, nc, width, height, image, np, props) 
integer*4 index, nc, width, height 
integer*4 image(*) 
integer*4 np 
real props(np) 

PARAMETERS 

index expects the name of the texture function being defined. Index 
is reserved as a null definition, and cannot be redefined. 

nc expects the number of 8-bit components per image pixel. 1, 2, 
3, and 4 component textures are supported. 

width expects the width of image in pixels. 

height expects the height of image in pixels. 

image expects an array of 4-byte words containing the pixel data. This 
image is in the format returned by lrectr, and accepted by 
lrectw. 

np expects the number of symbols and floating point values in 
props, including the termination symbol TXNULL. If np is 
zero, it is ignored. Operation over network connections is more 
efficient when np is correctly specified, however. 

props expects the array of floating point symbols and values that 
define the texture function, props must contain a sequence of 
symbols, each followed by the appropriate number of floating 
point values. The last symbol must be TXNULL, which is 
itself not followed by any values. 

DESCRIPTION 

A texture, or texture function, is a mapping of the texture coordinates s 
and t into 1, 2, 3, or 4 values, texdef defines such a mapping, named 
index, based on an image and a set of options. Currently texdef is the 
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only command available to specify such a mapping. Future Graphics 
Library releases may provide alternate mechanisms, however. 

The image accepted by texdef must be in the format defined by lrectr 
and pixmod, and must be packed with 8, 16, 24, or 32 bits per pixel, nc 
specifies both the number of bits per pixel expected in image, and the 
number of components, or values, that will be generated by the texture 
function. 



nc 


components 


bits per pixel 


1 


1 


8 


2 


2 


16 


3 


3 


24 


4 


4 


32 



A 2-component image, for example, is treated as two separate 1- 
component images. Each 1 -component image is used to define one tex- 
ture function output. The pixel byte with the lowest address is pixel 
component 0. The 1-component image defined by these bytes generates 
texture function output 0. Thus 32-bit image pixels packed in the usual 
ABGR manner generate four texture function outputs: alpha (output 0), 
blue (output 1), green (output 2), and red (output 3). Refer to the tevdef 
manual page for an explanation of how the 1, 2, 3, or 4 texture function 
outputs are used to modify pixel color. 

The dimensions of image are specified by width and height. These 
values must be positive, otherwise they are unconstrained. Note in par- 
ticular that image need not have dimensions that are a power of 2. 

Each texture function output is a filtered sampling of the corresponding 
image component, where texture coordinate s is used as the x address, 
and texture coordinate t is used as the y address. Regardless of the 
dimensions of the image, it is mapped into ^-coordinates such that its 
lower-left corner is (0,0), and its upper-right corner is (1,1). The way 
that s and t map onto the image when they are out of the range 0.0 
through 1 .0 is specified in the props array. 

A useful texture function can be defined by simply passing an image and 
a null props array to texdef. The options specified in the props array, 
however, allow significant control over both texture mapping quality 
and performance. The following symbols are accepted in props: 
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TXMINF specifies the filter function used to generate the texture 
function output when multiple image pixels correspond to one pixel 
on the screen. It is followed by a single symbol that specifies which 
minification filter to use. 

TXPOIN selects the value of the image pixel nearest to the 
exact s,t mapping onto the texture. 

TXBILI selects the weighted average of the values of the four 
image pixels nearest to the exact s,t mapping onto the texture. 
TXMMP chooses a prefiltered version of the image, based on 
the number of image pixels that correspond to one screen pixel, 
then selects the value of the pixel that is nearest to the exact s,t 
mapping onto that image. 

TXMML chooses the two prefiltered versions of the image that 
have the nearest image-pixel to screen-pixel size correspon- 
dence, then selects the weighted average of the values of the 
pixel in each of these images that is nearest the exact s,t map- 
ping onto that image. 

TXMMBL chooses a prefiltered version of the image, based on 
the number of image pixels that correspond to one screen pixel, 
then selects the weighted average of the values of the four pixels 
nearest to the exact s,t mapping onto that image. 

The default minification filter is TXMML. Prefiltered versions of 
the image, when required by the minification filter, are computed 
automatically by the Graphics Library. 

TXMAGF specifies the filter function used to generate the texture 
function output when multiple screen pixels correspond to one 
image pixel. It is followed by a single symbol that specifies which 
magnification filter to use. The magnification filter symbols are: 

TXPOIN selects the value of the image pixel nearest to the 
exact s,t mapping onto the texture. 

TXBILI selects the weighted average of the values of the four 
image pixels nearest to the exact $,t mapping onto the texture. 
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The default magnification filter is TXBILL 

TXWRAP specifies how texture coordinates outside the range 0.0 
through 1.0 are handled. 

TXREPE uses the fractional parts of the texture coordinates. f 

TXCLAM clamps the texture coordinates to the range 0.0 V 
through 1.0. 

The default texture coordinate handling is TX JREPE, 

TXWRPS is like TXWRAP, but it specifies behavior only for the s 
texture coordinate. 

TXWRPT is like TXWRAP, but it specifies behavior only for the t 
texture coordinate. 

TXTTLE specifies a subregion of an image to be turned into a tex- 
ture. It is followed by four floating point coordinates that specify 
the x and y coordinates of the lower-left corner of the subregion, 
then the x and y coordinates of the upper-right corner of the subre- 
gion. The original texture image continues to be addressed in the 
range 0,0 through 1,1. However, the subregion occupies only a frac- 
tion of this space, and pixels that map outside the subregion are not | 
drawn. 

If the image (or the specified subregion) is larger than can be handled by 
the hardware, it is reduced to the maximum supported size automatically 
(with no indication other than the resulting visual quality). Because 
subregions are specified independently, they should all be the same size 
(otherwise some may be reduced and others not). 

TXTTLE supports mapping of high-resolution images with multiple 
rendering passes. By splitting the texture into multiple pieces, each 
piece can be rendered at the maximum supported texture resolution. For 
example to render a scene with 2x texture resolution, texdef is called 
four times with different indices, one for each quadrant of the original 
texture. The scene is then drawn four times, each time calling texbin 
with the texture id of one of the four quadrants. In each pass, only the 
pixels whose texture coordinates map within that quadrant are drawn. 
Pixels outside of this quadrant are effectively clipped. 



( 
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SEE ALSO 

afunct, scrsub, t, tevbin, tevdef , texbin, texgen 

NOTES 

IRIS-4D G, GT, and GTX models, and the Personal Iris, do not support 
texture mapping, texdef is ignored by these machines. Use getgde to 
determine whether texture mapping is supported. 

It is acceptable to define a 4-component texture function on an ERIS-4D 
VGX system that does not have alpha bitplanes. However, this 
definition will be treated as a 3-component definition by tevdef. Use 
getgde(GDBNS A) to determine whether alpha bitplanes are available. 

Points, lines, and characters, as well as polygons, are texture mapped. 
Filter selection and wrap modes are applicable to lines. Points are 
filtered by the magnification filter, assuming a 1-to-l correspondence 
between texture pixel and screen pixel size. Characters use the same 
magnification filter, but are mapped assuming that both s and t are zero. 

IRIS screen pixels have integer coordinates at their centers. Texture 
images, however, have integer coordinates (0 and 1) at their exact edges, 
not at the centers of pixels on their edges. 

BUGS 

IRIS-4D VGX models require that, when using TXTILE, width and 
height of both the original image and the specified subregion be a power 
of 2. Also, texture coordinate t is always clamped to the range 0.0 
through 1.0 in this case, regardless of the value of TXWRPT. 

IRIS-4D VGX models require that, when TXWRPS is set to 
TXCLAM, TXWRPT also be set to TXCLAM. Otherwise operation 
is undefined. 



Version 3.0 - 5 - April 1 990 



texgen Graphics Reference, FORTRAN texgen 

NAME 

texgen - specify automatic generation of texture coordinates 

FORTRAN SPECIFICATION 

subroutine texgen(coord, mode, params) 
integer*4 coord, mode 
realparamsQ 

PARAMETERS 

coord Expects the name of the texture coordinate whose generation is 
to be defined, enabled, or disabled. One of: 

TXS: The s texture coordinate 

TXT: The nexture coordinate 

mode Expects the mode of generation to be specified, or an indication 
that generation is to be either enabled or disabled. One of the 
symbolic constants: 

TGCONT: Use the plane equation specified in params to 
define a plane in eye-coordinates. Generate a texture coordi- 
nate that is proportional to vertex distance from this plane. 

TXLINE: Use the plane equation specified in params to define 
a plane in object-coordinates. Generate a texture coordinate 
that is proportional to vertex distance from this plane. 

TGON: Enable the (previously defined) replacement for the 
specified texture coordinate. 

TGOFF: Disable replacement of the specified texture coordi- 
nate (the default). 

params Expects a 4-component plane equation when mode is 
TGCONT or TGLINE. Array element 1 is plane equation 
component A, 2 is B, 3 is C, and 4 is D. The contents of 
params are insignificant when mode is TGON or TGOFF. 



( 
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DESCRIPTION 

Texture coordinates s and t can be specified directly using the t com- 
mand. It is also possible to have texture coordinates generated automat- 
ically as a function of object geometry, texgen specifies, enables, and 
disables such automatic generation. Either or both texture coordinates 
can be generated independently. Automatic texture coordinate genera- 
tion is disabled by default. 

texgen supports two generation algorithms. TGLINE operates directly 
on object coordinates, and is therefore most useful for textures that are 
locked to objects, such as ground texture locked to a terain, or metalic 
texture locked to a cylinder. TGCONT operates on eye-space coordi- 
nates. It supports motion of an object through a 'field' of texture coordi- 
nates. 

Both modes TGLINE and TGCONT define a texture coordinate gen- 
eration function that is a linear function of distance from a plane. The 
plane equation is specified as a single, 4-component, vector in object 
coordinates. 



object ' 



The TGLINE plane equation remains in object-coordinates. The 
TGCONT plane equation is transformed by the ModelView matrix into 
eye-coordinates when it is defined: 

* eye = ^ ModelView "object 

When a generation function has been defined for a texture coordinate, 
and texgen has been called with TGON, each vertex presented to the 
graphics system has that texture coordinate value replaced with the dis- 
tance of the vertex from the defined plane. For example, when texture 
coordinate s is generated by a TGLINE function, the generation func- 
tion is: 



S ~~ * object * object ' 



^object, y object, z object, ^object 
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Alternately, when t is generated by a TGCONT function, the generation 
function is: 

t — V'P 

1 v eye l eye 

where 

* eye = * object ^ ModelView t 

and 

* eye = ^ ModelView * object 

Note that the ModelView matrix that modifies the plane equation is the 
ModelView matrix in effect when texgen was called, while the Model- 
View matrix that modifies the vertex coQrdinates is the matrix used to 
transform that vertex. 

texgen generation functions remain valid until they are redefined. They 
are enabled and disabled without redefinition by calls to texgen with 
modes TGON and TGOFF. texgen definition has no effect on the 
enable mode of the texture generation function. 

When enabled, texgen replaces s, U or both each time a vertex command 
is received. A texture coordinate that is not being generated continues 
to be specified by t commands. Texture coordinate are transformed by 
the Texture matrix (see mmode) following coordinate replacement by 
texgen. 

SEE ALSO 

mmode, t, texdef, texbin, tevdef, tevbin 

NOTES 

IRIS-4D G, GT, and GTX models, and the Personal Iris, do not support 
texture mapping, texgen is ignored by these machines. Use getgde to 
determine whether texture mapping is supported. 

texgen cannot be used while mmode is MSINGL. 
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NAME 

textco - sets the color of text in the textport 

FORTRAN 77 SPECIFICATION 

subroutine textco(tcolor) 
integer*4 tcolor 

PARAMETERS 

tcolor expects an index into the current color map. 

DESCRIPTION 

textco sets the color of all the text in the textport of the calling process. 
If the calling process was invoked from a wsh window, this window is 
used for its textport; otherwise, the process does not have a textport and 
this routine does nothing. 

SEE ALSO 

pageco 

wsh(l) in the User' s Reference Manual 

NOTES 

This routine is available only in immediate mode. 

A process launched from 4Sight or The IRIS Workspace™ will not have 
a textport. Therefore, we do not recommend the use of this routine in 
new development. 
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NAME 

textin - initializes the textport 

FORTRAN 77 SPECIFICATION 
subroutine textin 

PARAMETERS 

none 

DESCRIPTION 

textin initializes the textport of the calling process to its default size, 
location, textcolor, and pagecolor. If the calling process was invoked 
from a wsh window, this window is used for its textport; otherwise, the 
process does not have a textport and this routine does nothing. 

SEE ALSO 

pageco, textco, textpo, tpon 

wsh(l) in the User' s Reference Manual \^ 

NOTES 

This routine is available only in immediate mode. 

A process launched from 4Sight or The IRIS Workspace™ will not have 
a textport. Therefore, we do not recommend the use of this routine in 
new development. 



c 
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NAME 

textpo - positions and sizes the textport 

FORTRAN 77 SPECIFICATION 

subroutine textpo(left, right, bottom, top) 
integer*4 left, right, bottom, top 

PARAMETERS 

left expects x screen coordinate for the left side of the textport. 

right expects x screen coordinate for the right side of the textport. 

bottom expects y screen coordinate for the bottom of the textport. 

top expects y screen coordinate for the top of the textport. 

DESCRIPTION 

textpo positions and sizes the textport of the calling process to the 
specified rectangle. If the calling process was invoked from a wsh win- 
dow, this window is used for its textport; otherwise, the process does not 
have a textport and this routine does nothing. 

SEE ALSO 
textin, tpon 
wsh(l) in the User's Reference Manual. 

NOTES 

This routine is available only in immediate mode. 

A process launched from 4Sight or The IRIS Workspace™ will not have 
a textport. Therefore, we do not recommend the use of this routine in 
new development. 
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NAME 

tie - ties two valuators to a button 

FORTRAN 77 SPECIFICATION 

subroutine tie(b, vl, v2) I 

integer *4 b, vl, v2 

PARAMETERS 

b expects a button. 
vl expects a valuator. 
v2 expects a valuator. 

DESCRIPTION 

tie requires a button h and two valuators vl and v2 . When a queued but- 
ton changes state, three entries are made in the queue: one records the 
current state of the button and two record the current positions of each 
valuator. The valuators vl and v2 need not be (and probably should not ^ 
be) queued. I 

You can tie one valuator to a button by calling tie with v2 set to 
NULLDEV. You can untie a button by calling tie with both vl and v2 
set to NULLDEV. vl appears before v2 in the event queue; b precedes 
both vl and v2 . 

SEE ALSO 

getbut 

NOTES 

This routine is available only in immediate mode. 
The symbol NULLDEV is defined in <gllfdevice.h> . 



c 
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NAME 

tpon, tpoff- control the visibility of the textport 

FORTRAN 77 SPECIFICATION 
subroutine tpon 
subroutine tpoff 

PARAMETERS 

none 

DESCRIPTION 

tpon pops the textport of the calling process, bringing it to the front of 
any windows that conceal it. tpoff pushs the textport down behind all 
other windows, effectively hiding it. If the calling process was invoked 
from a wsh window, this window is used for its textport; otherwise, the 
process does not have a textport and this routine does nothing. 

SEE ALSO 

textin, textpo 

wsh(l) in the User' $ Reference Manual. 

NOTES 

This routine is available only in immediate mode. 

A process launched from 4Sight or The IRIS Workspace™ will not have 
a textport. Therefore, we do not recommend the use of these routines in 
new development. 



Version 3.0 -1- April 1990 



transl Graphics Reference, FORTRAN transl 

NAME 

transl - translates graphical primitives 

FORTRAN 77 SPECIFICATION 

subroutine transl(x, y, z) I 

realx, y ? z 

PARAMETERS 

x expects the x coordinate of a point in object space. 
y expects the y coordinate of a point in object space. 
i expects the z coordinate of a point in object space. 

DESCRIPTION 

transl moves the object space origin to a point specified in the current 
object coordinate system. The transl routine is a modeling routine 
which changes the current transformation matrix. All objects drawn 
after transl executes are translated. Use pushma and popmat to limit ^ 

the scope of the translation. 1 

SEE ALSO 

mmode, popmat, pushma, rotate, scale 



c 
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NAME 

underl - allocates bitplanes for display of underlay colors 

FORTRAN 77 SPECIFICATION 

subroutine underl(planes) 
integer*4 planes 

PARAMETERS 

planes expects the number of bitplanes to be allocated for underlay 
colors. Valid values are (the default), 2, 4, and 8. 

DESCRIPTION 

The IRIS physical framebuffer is divided into four separate GL frame- 
buffers: normal, popup, overlay, underlay. Because a single physical 
framebuffer is used to implement the four GL framebuffers, bitplanes 
must be allocated among the GL framebuffers. underl specifies the 
number of bitplanes to be allocated to the underlay framebuffer. underl 
does not take effect immediately. Rather, it is considered only when 
gconfi is called, at which time all requests for bitplane resources are 
resolved. 

While only one of the four GL framebuffers can be drawn to at a time 
(see drawmo), all four are displayed simultaneously. The decision of 
which to display at each pixel is made based on the contents of the four 
framebuffers at that pixel location, using the following hierarchical rule: 

if the popup pixel contents are non-zero 

then display the popup bitplanes 

else if overlay bitplanes are allocated AND 
the overlay pixel contents are non-zero 

then display the overlay bitplanes 

else if the normal pixel contents are non-zero OR 
no underlay bitplanes are allocated 
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then display the normal bitplanes 

else display the underlay bitplanes 

Thus images drawn into the overlay framebuffer appear over images in 
the normal framebuffer, and images drawn into the underlay framebuffer 
appear under images in the normal framebuffer. Popup images appear 
over everything else. 

The default configuration of the underlay framebuffer is bitplanes. To 
make a change to this configuration other than to change the bitplane 
size, the drawing mode must be UNDERD. For example, the underlay 
framebuffer can be configured to be double buffered by calling double 
while draw mode is UNDERD. 

On models that cannot support overlay and underlay bitplanes simul- 
taneously, calling underl with a non-zero argument forces overla to 
zero. When simultaneous overlay and underlay operation is supported, 
calling underl may have no effect on the number of overlay bitplanes. 

SEE ALSO 

double, drawmo, gconfi, getgde, single, underl 

NOTES 

This routine is available only in immediate mode. 

IRIS-4D G, GT, and GTX models, and the Personal Iris, support only 
single buffered, color map mode underlay bitplanes. 

The Personal Iris supports or 2 underlay bitplanes. There are no over- 
lay or underlay bitplanes in the minimum configuration of the Personal 
Iris. 

IRIS-4D GT and GTX models support 0, 2, or 4 underlay bitplanes. 
Because 4-bitplane allocation reduces the popup framebuffer to zero bit- 
planes, however, its use is strongly discouraged. The window manager 
cannot operate properly when no popup bitplanes are available. 

IRIS-4D VGX models support 0, 2, 4, or 8 underlay bitplanes, either 
single or double buffered, in color map mode only. The 4 and 8 bitplane 
allocations utilize the alpha bitplanes, which must be present, and which 
therefore are unavailable in draw mode NORMAL. 
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BUGS 



The Personal Iris does not support shade model GOURAU in the under- 
lay framebuffer. 
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NAME 

unqdev - disables the specified device from making entries in the event 
queue 



FORTRAN 77 SPECIFICATION 



subroutine unqdev(dev) 
integer*4 dev 



PARAMETERS 

dev expects a device identifier 

DESCRIPTION 

unqdev removes the specified device from the list of devices whose 
changes are recorded in the event queue. If a device has recorded events 
that have not been read, they remain in the queue. 

Use qreset to flush the event queue. 

SEE ALSO ( 

qdevic, qreset 

NOTE 

This routine is available only in immediate mode. 



c 
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NAME 

v2d, v2f, v2i, v2s, v3d, v3f, v3i, v3s, v4d, v4f, v4i, v4s - transfers a 2- 
D, 3-D, or 4-D vertex to the graphics pipe 

FORTRAN 77 SPECIFICATION 

subroutine v2s(vector) subroutine v2f(vector) 

integer*2 vector(2) real vector(2) 

subroutine v2i(vector) subroutine v2d(vector) 

integer*4 vector(2) double precision vector(2) 

subroutine v3s(vector) subroutine v3f(vector) 

integer*2 vector(3) real vector(3) 

subroutine v3i(vector) subroutine v3d(vector) 

integer*4 vector(3) double precision vector(3) 

subroutine v4s(vector) subroutine v4f(vector) 

integer*2 vector(4) real vector(4) 

subroutine v4i(vector) subroutine v4d(vector) 

integer *4 vector(4) double precision vector(4) 

PARAMETERS 

vector expects a 2, 3, or 4 element array, depending on whether you 
call the v2, v3, or v4 version of the routine. The elements of the 
array are the coordinates of the vertex (point) that you want to 
transfer to the graphics pipe. Put the x coordinate in element 1, 
the y coordinate in element 2, the z coordinate in element 3 (for 
v3 and v4), and the w coordinate in element 4 (for v4). 

DESCRIPTION 

v transfers a single 2-D (v2), 3-D (v3), or 4-D (v4) vertex to the graphics 
pipe. The coordinates are passed to v as an array. Separate subroutines 
are provided for 16-bit integers (s), 32-bit integers limited to a signed 
24-bit range (i), 32-bit IEEE single precision floats (f), and 64-bit IEEE 
double precision floats (d). The z coordinate defaults to 0.0 if not 
specified, w defaults to 1.0. 
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The Graphics Library subroutines bgnpoi, endpoi, bgnlin, endlin, 
bgnclo, enddo, bgnpoi, endpoi, bgntme, endtme, bgnqst, and endqst 

determine how the vertex is interpreted. For example, vertices specified 
between bgnpoi and endpoi draw single pixels (points) on the screen. 
Likewise, those specified between bgnlin and endlin draw a sequence 
of lines (with the line stipple continued through internal vertices). | 
Closed lines return to the first vertex specified, producing the equivalent ^ 
of an outlined polygon. 

Vertices specified when none of bgnpoi, bgnlin, bgnclo, bgnpoi, 
bgntme, and bgnqst are active simply set the current graphics position. 
They do not have any effecrt on the frame buffer contents. (Refer to the 
pages for bgnpoi, bgnlin, bgnclo, bgnpoi, bgntme, and bgnqst for 
their effect on the current graphics position.) 

SEE ALSO 

bgnclo, bgnlin, bgnpoi, bgnpoi, bgntme, bgnqst 



c 



( 
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NAME 

videoc - initiates a command transfer sequence on an optional video 
peripheral 

FORTRAN 77 SPECIFICATION 

subroutine videoc(cmd) 
integer*4 cmd 

PARAMETERS 

cmd expects a command value which initiates a command transfer 
sequence on a video peripheral. The valid command tokens are: 

VPJNITNTSCCOMP initialize the optional Live Video Digi- 
tizer for a composite NTSC video source. 

VPJNITNTSC JIGB initialize the Live Video Digitizer for a 
RGB NTSC video source. 

VPJNITPALCOMP initialize the Live Video Digitizer for a 
composite PAL video source. 

VPJDMITPALRGB initialize the Live Video Digitizer for a 
RGB PAL video source. 

DESCRIPTION 

videoc allows you to initialize the Live Video Digitizer peripheral 
board. Four command tokens are recognized; these initialize the board 
for either an NTSC video source (composite or RGB) or a PAL video 
source (composite or RGB). 

SEE ALSO 

getmon, getoth, setmon, setvid 
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NOTES 

This routine is available only in immediate mode. 

The Live Video Digitizer is available as an option for IRIS-4D GTX 
models only. ^ 

For C, the symbolic constants named above are defined in the file \ 
<gllvpLh>. You will need to create your own version of it for FOR- 
TRAN 77. 



( 



( 
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NAME 

viewpo - allocates an area of the window for an image 

FORTRAN 77 SPECIFICATION 

subroutine viewpo(left, right, bottom, top) 
integer*4 left, right, bottom, top 

PARAMETERS 

left expects x location (in pixels) of left side of viewport. 

right expects x location (in pixels) of right side of viewport. 

bottom expects j; location (in pixels) of bottom of viewport. 

top expects y location (in pixels) of top of viewport. 

DESCRIPTION 

viewpo specifies, in pixels, the area of the window that displays an 
image. The viewport locations are specified relative to the lower-left 
corner of the window. Specifying the viewport is the first step in map- 
ping world coordinates to screen coordinates. The portion of world 
space that window, ortho, or perspe describes is mapped into the 
viewport, left, right, bottom, top coordinates define a rectangular area 
on the screen. 

viewpo also loads the screenmask. 

SEE ALSO 

scrmas, getvie, popvie, pushvi 

NOTE 

On the Personal Iris, if left is greater than right or bottom is greater than 
top, the screen displays a reflected image. 
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NAME 

winatt - obsolete routine 

FORTRAN 77 SPECIFICATION 
integer*4 function winattQ 

PARAMETERS 

none 

DESCRIPTION 

This routine is obsolete and does not function. Currently, there is no 
replacement. 

NOTE 

This routine is available only in immediate mode. 
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NAME 

winclo - closes the identified graphics window 

FORTRAN 77 SPECIFICATION 

subroutine winclo(gwid) I 

integer*4 gwid 

PARAMETERS 

gwid expects the identifier for the graphics window that you want 
closed. 

DESCRIPTION 

winclo closes the graphics window associated with identifier gwid. The 
identifier for a window is the function return value from the call to 
winope that created the window. 

When using the Distributed Graphics Library (DGL), the graphics win- 
dow identifier also identifies the graphics server associated with the win- 
dow. The DGL directs all subsequent Graphics Library input and output f 
to the server associated with gwid. ^ 

If the window being closed is on a screen for which the getgde inquiry 
GDSTYP returns GDSTNW, winclo leaves the image undisturbed. 

SEE ALSO 

getgde, winope 

NOTE 

This routine is available only in immediate mode. 



( 
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NAME 

wincon - binds window constraints to the current window 

FORTRAN 77 SPECIFICATION 
subroutine wincon 

PARAMETERS 

none 

DESCRIPTION 

wincon binds the currently specified constraints to the current graphics 
window. (Logically, because this assumes the existence of a current 
graphics window, you must have previously called winope.) Prior to 
calling wincon you can set the the values of the window constraints by 
using the following commands: minsiz, maxsiz, keepas, prefsi, iconsi, 
nobord, noport, stepun, fudge, and imakeb. Note the absence from 
this list of prefpo; the position of a window can not be constrained. 

After binding these constraints to a window, wincon resets the window 
constraints to their default values, if any. 

SEE ALSO 

fudge, keepas, iconsi, imakeb, maxsiz, minsiz, nobord, noport, prefpo, 
prefsi, stepun, winope 

NOTE 

This routine is available only in immediate mode. 
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NAME 

windep - measures how deep a window is in the window stack 

FORTRAN 77 SPECIFICATION 

integer*4 function windep(gwid) / 

integer*4 gwid ^ 

PARAMETERS 

gwid expects the window identifier for the window you want to test. 

FUNCTION RETURN VALUE 

The returned value of this function is a number that you can use to 
determine that stacking order of windows on the screen. 

DESCRIPTION 

windep returns a number which can be compared against the windep 
return value for other windows to determine the stacking order of a 
program's windows on the screen. | 

When using the Distributed Graphics Library DGL), the graphics win- 
dow identifier also identifies the graphics server associated with the win- 
dow. The DGL directs all subsequent Graphics Library input and output 
to the server associated with gwid. 

SEE ALSO 

winpus, winpop 

NOTE 

This routine is available only in immediate mode. 
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NAME 

window - defines a perspective projection transformation 

FORTRAN 77 SPECIFICATION 

subroutine window(left, right, bottom, top, near, far) 
real left, right, bottom, top, near, far 

PARAMETERS 

left expects x coordinate of left side of viewing volume. 

right expects x coordinate of right side of viewing volume. 

bottom expects y coordinate of bottom of viewing volume. 

top expects y coordinate of top of viewing volume. 

near expects the z coordinate of the near clipping plane. 

far expects the z coordinate of the far clipping plane. 

DESCRIPTION 

window specifies the position and size of the rectangular viewing frus- 
tum closest to the eye (in the near clipping plane), and the location of 
the far clipping plane. All objects contained within this volume are pro- 
jected in perspective onto the screen area that viewpo defines. 

When the system is in single matrix mode, window loads a matrix onto 
the transformation stack, replacing the current top matrix. When the 
system is in viewing, projection, or texture matrix mode, window 
replaces the current Projection matrix and leaves the ModelView matrix 
stack and the Texture matrix unchanged. 

SEE ALSO 

mmode, ortho, perspe, viewpo 
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NAME 

winget - returns the identifier of the current graphics window 

FORTRAN 77 SPECIFICATION 

integer*4 function winget() | 

PARAMETERS 
none 

FUNCTION RETURN VALUE 

The returned value for this function is the identifier of the current graph- 
ics window. 

DESCRIPTION 

winget returns the identifier of the current graphics window. The 
current graphics window is the window to which the system directs the 
output from graphics routines. 

SEE ALSO ^ 

winset 

NOTE 

This routine is available only in immediate mode. 
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NAME 

winmov - moves the current graphics window by its lower-left corner 

FORTRAN 77 SPECIFICATION 

subroutine winmov 
integer*4 orgx, orgy 

PARAMETERS 

orgx expects the x coordinate of the location to which you want to 
move the current graphics window. 

orgy expects the y coordinate of the location to which you want to 
move the current graphics window. 

DESCRIPTION 

winmov moves the current graphics window so that its origin is at the 
screen coordinates (in pixels) specified by orgx, orgy. The origin of the 
current graphics window is its lower-left corner, winmov does not 
change the size and shape of the window. 

SEE ALSO 

winpos 

NOTE 

This routine is available only in immediate mode. 
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NAME 

winope - creates a graphics window 

FORTRAN 77 SPECIFICATION 

integer*4 function winope(name, length) f 

character 8 ^*) name 
integer*4 length 

PARAMETERS 

name expects the window title that is displayed on the left hand side 
of the title bar for the window. If you do not want a title, pass a 
zero-length string. 

length expects the length of the string in name. 
FUNCTION RETURN VALUE 



The returned value for this function is the graphics window identifier for 
the window just created. Use this value to identify the graphics window 
to other windowing functions. Only the lower 16 bits are significant, 
since a graphics window identifier is the value portion of a REDRAW 
event queue entry. If no additional windows are available, this function 
returns — 1. 

DESCRIPTION 

winope creates a graphics window as defined by the current values of 
the window constraints on the currently selected screen. This new win- 
dow becomes the current window. If this is the first time that your pro- 
gram has called winope, the system also initializes the Graphics 
Library. 

Except for size and location, the system maintains default values for the 
constraints on a window. You can change these default window con- 
straints if you call the routines minsiz, maxsiz, keepas, prefsi, prefpo, 
stepun, fudge, iconsi, nobord, noport, imakeb, and foregr before you 
call winope. If the a window's size and location (or both) are left 
unconstrained, the system allows the user to place and size the window. 



( 



c 
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The selected screen defaults to the screen with the input focus at the 
time the first Graphics Library routine is called. You can change it 
using the routine scrnse. 

winope sets the graphics state of the new window (this includes window 
constraints) to its default values; there are listed in the table below. It 
also queues the pseudo devices INPTCH and REDRAW. 

When using the Distributed Graphics Library (DGL), the window 
identifier also identifies the window's graphics server. The DGL directs 
all graphics input and output to the current window's server; subsequent 
Graphics Library subroutines are executed by the window's server. 



State 


Default Value 


acsize 





afunct 


AFALWA 


backbu 


.FALSE. 


backfa 


.FALSE. 


blendf 


BFONE, BFZERO 


buffer mode 


single 


character position 


undefined 


clippl 


CPOFF 


color 





color mode 


single color map 




(cmode and onemap) 


concav 


.FALSE. 


curvep 


undefined 


depth range 


Zmin, Zmax 


depthc 


.FALSE. 


drawmo 


NORMDR 


feedback mode 


off 


fogver 


FGOFF 


font 





frontb 


.TRUE. 


frontf 


.FALSE. 


full screen mode 


off 
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State 


Default Value 


glcomp 




GLCOLD 


1 


GLCZRA 


1 (B and G models) 




(other models) 


graphics position 


undefined 


linesm 


SMLOFF 


linest 


(solid) 


linewi 


1 


lmcolo 


LMCCOL 


Imdef 




LIGHT/i 





LMODEL 





MATERI 





logico 


LOSRC 


lsrepe 


1 


mapcol 


no entries changed 


matrix 




ModelView 


undefined 


Projection 


undefined 


Single 


ortho2 matching window size 


Texture 


undefined 


mmode 


MSINGL 


name stack 


empty 


nmode 


NAUTO 


normal vector 


undefined 


overla 


2 


patchb 


undefined 


patchc 


undefined 


patchp 


undefined 


pattern 


(solid) 


pick mode 


off 


picks! 


10x10 


pixmod 


standard 


pntsmo 


SMPOFF 


polymo 


PYMFIL 



c 
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State 


Default Value 


polysm 


PYSMOF 


readso 


SRCAUT 


rectzo 


1.0, 1.0 


RGB color 


all components 




(when RGB mode is entered) 


RGB shade range 


undefined 


RGB writemask 


all components OxFF 




(when RGB mode is entered) 


scrbox 


SBRESE 


scrmas 


size of window 


scrsub 


SSOFF 


select mode 


off 


shade range 


0, 7, Zmin, Zmax 


shadem 


GOURAU 


stenci 


disabled 


stensi 





swrite 


all planes enabled 


tevbin 


0(off) 


texbin 


0(off) 


texgen 


TGOFF 


underl 





viewpo 


size of window 


writem 


all planes enabled 


zbuffe 


.FALSE. 


zdraw 


.FALSE. 


zfunct 


ZFLEQU 


zsourc 


ZSRCDE 


zwrite 


all planes enabled 



Notes 

• Font is a Helvetica-like font. 



Zmin and Zmax are the minimum and maximum values that you can 
store in the z-buffer. These depend on the graphics hardware and 
are returned by getgde(GDZMIN) and getgde(GDZMAX). 
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• On IRIS-4D B and G models, winope also sets lsback(.FALSE.) 
and resetl(.TRUE.). 

SEE ALSO 

foregr, fudge, iconsi, imakeb, keepas, minsiz, maxsiz, nobord, noport, 
prefsi, prefpo, scmse, stepun, winclo 

4Sight User's Guide, "Using the GL/DGL Interfaces". 

NOTE 

This routine is available only in immediate mode. 



c 



c 
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NAME 

winpop - moves the current graphics window in front of all other win- 
dows 

FORTRAN 77 SPECIFICATION 
subroutine winpop 

PARAMETERS 
none 

DESCRIPTION 

When more than one window tries to occupy the same space on the 
screen, the system stacks them on top of each other— thus obscuring 
(either partially or completely) the underlying graphics window or win- 
dows. 

Use winpop to take the current graphics window from anywhere in the 
stack of windows and place it on top. 

SEE ALSO 

winpus 

NOTE 

This routine is available only in immediate mode. 
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NAME 

winpos - changes the size and position of the current graphics window 

FORTRAN 77 SPECIFICATION 

subroutine winpos(xl, x2, yl, y2) I 

integer*4 xl ? x2 ? yl ? y2; 

PARAMETERS 

xl expects the x screen coordinate (in pixels) of the first corner of the 
new location for the current graphics window. The first corner of 
the new window is the corner diagonally opposite the second 
corner. 

x2 expects the x screen coordinate (in pixels) of the second corner of 
the new location for the current graphics window. 

yl expects the y screen coordinate (in pixels) of the first corner of the 
new location for the current graphics window. 

y2 expects the y screen coordinate (in pixels) of the second corner of ^ 
the new location for the current graphics window. I 

DESCRIPTION 

winpos moves and reshapes the current graphics window to match the 
screen coordinates xl,x2,yl, y2 (calculated in pixels). This differs from 
prefpo because the reshaped window is not fixed in size and shape, and 
can be reshaped interactively. 

SEE ALSO 

prefpo, prefsi, winmov 



NOTE 

This routine is available only in immediate mode. 



( 
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NAME 

winpus - places the current graphics window behind all other windows 

FORTRAN 77 SPECIFICATION 
subroutine winpus 

PARAMETERS 

none 

DESCRIPTION 

When more than one window tries to occupy the same space on the 
screen, the system stacks them on top of each other — thus obscuring 
(either partially or completely) the underlying graphics window or win- 
dows. 

Use winpus to take the current graphics window from anywhere in the 
stack of windows and push it to the bottom. 

SEE ALSO 

winpop 

NOTE 

This routine is available only in immediate mode. 



Version 3.0 -1- April 1990 



winset Graphics Reference, FORTRAN winset 

NAME 

winset - sets the current graphics window 

FORTRAN 77 SPECIFICATION 

subroutine winset(gwid) f 

integer*4 gwid 

PARAMETERS 

gwid expects a graphics window identifier. 

DESCRIPTION 

winset takes the graphics window associated with identifier gwid and 
makes it the current window. The system directs all graphics output to 
the current graphics window. 

When using the Distributed Graphics Library (DGL), the graphics win- 
dow identifier also identifies the graphics server associated with the win- 
dow. The DGL directs all subsequent Graphics Library input and output 
to the server associated with gwid. f 

SEE ALSO 

winget 

NOTE 

This routine is available only in immediate mode. 



c 
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NAME 

wintit - adds a title bar to the current graphics window 

FORTRAN 77 SPECIFICATION 

subroutine wintit(name, length) 
character*(*) name 
integer*4 length 

PARAMETERS 

name expects the title you want displayed in the title bar of the current 
graphics window. 

length expects the length of the name string. 

DESCRIPTION 

wintit adds a title to the current graphics window. Use wintit(", 0) to 
clear the title. 

SEE ALSO 

winope 

NOTE 

This routine is available only in immediate mode. 
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NAME 

wmpack - specifies RGBA writemask with a single packed integer 

FORTRAN 77 SPECIFICATION 

subroutine wmpack(pack) I 

integer*4 pack 

PARAMETERS 

pack expects a packed integer containing the RGBA (red, green, blue, 
alpha) values you want to assign as the current write mask. 
Expressed in hexadecimal, the format of the packed integer is 
$aabbggrr, where: 

aa is the alpha value, 

bb is the blue value, 

gg is the green value, and 

rr is the red value. 



RGBA component values range from to $FF (255). 

DESCRIPTION 

wmpack sets the red, green, blue, and alpha write mask components of 
the currently active GL framebuffer, one of normal, popup, overlay, or 
underlay as specified by drawmo. The current framebuffer must be in 
RGB mode for the wmpack command to be applicable. All drawing 
into the color bitplanes of the current framebuffer is masked by the 
current write mask. Write mask components are retained in each draw 
mode, so when a draw mode is re-entered, the red, green, blue, and 
alpha masks are reset to the last values specified in that draw mode. 

Each write mask component is an 8-bit mask, which allows changes 
only to bitplanes corresponding to ones in the mask. For example, 
wmpack($FF0000F0) allows changes only to the 4 most significant bits 
of red, and to all the bits of alpha. 

It is an error to call wmpack while the current framebuffer is in color 
map mode. 



( 



( 
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The write mask components of all firamebuffers in RGB mode are set to 
$FF when gconfi is called. 

SEE ALSO 

cpack, drawmo, gRGBma, RGBmod 



NOTE 



Because only the normal framebuffer currently supports RGB mode, 
wmpack should be called only while draw mode is NORMAL. Use 
getgde to determine whether RGB mode is available in draw mode 
NORMAL. 
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NAME 

writem - grants write permission to bitplanes 

FORTRAN 77 SPECIFICATION 

subroutine writem(wtm) | 

integer*4 wtm ^ 

PARAMETERS 

wtm expects a mask whose bits control which bitplanes are available 
for drawing and which are read only. 

The mask contains one bit per available bitplane. If a bit is set in 
the writemask, the system writes the current color index into the 
corresponding bitplane. If a bit is set to zero in the writemask, the 
corresponding bitplane is read-only. 

DESCRIPTION 

Use writem to reserve bitplanes for special purposes. When the wri- 
temask marks a biplane as read-only, that bitplane is write protected f 
from ordinary drawing routines. V 

Use RGBwri in RGB mode. 

SEE ALSO 

color, drawmo, RGBwri 



( 
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NAME 

writep - paints a row of pixels on the screen 

FORTRAN 77 SPECIFICATION 

subroutine writep(n, colors) 
integer*4 n 
integer*! colors(n) 

PARAMETERS 

n expects the number of pixels you want to paint. 

colors expects an array of color indices. The system reads n elements 
from this array and writes a pixel of the appropriate color for 
each. 

DESCRIPTION 

writep paints a row of pixels on the screen in color map mode. The 
starting location is the current character position. The system updates 
the current character position to one pixel to the right of the last painted 
pixel. The system paints pixels from left to right, and clips to the 
current screenmask. 

writep does not automatically wrap from one line to the next. The 
current character position becomes undefined if the new position is out- 
side the viewport. 

The system must be in color map mode for writep to function correctly. 

SEE ALSO 

lrectw 

NOTES 

writep should not be used in new development. Rather, pixels should 
be written using the high-performance lrectw command. 
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This routine is available only in immediate mode. 
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NAME 

writeR - paints a row of pixels on the screen 

FORTRAN 77 SPECIFICATION 

subroutine writeR(n, red, green, blue) 

integer*4 n 

character*(*) red, green, blue 

PARAMETERS 

n expects the number of pixels that you want to paint. 

red expects an array containing red values for the pixels you paint. 
You need a red value for each pixel you paint. 

green expects an array containing green values for the pixels you paint. 
You need a green value for each pixel you paint. 

blue expects an array containing blue values for the pixels you paint. 
You need a blue value for each pixel you paint. 

DESCRIPTION 

writeR paints a row of pixels on the screen in RGB mode. The starting 
location is the current character position. The system updates the 
current character position to one pixel to the right of the last painted 
pixel. Pixels are painted from left to right, and are clipped to the current 
screenmask. writeR does not automatically wrap from one line to the 
next. The current character position becomes undefined if the new posi- 
tion is outside the viewport. 

writeR supplies a 24-bit RGB value (8 bits for each color) for each 
pixel. This value is written directly into the bitplanes. 

SEE ALSO 

lrectw 
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NOTES 

writeR should not be used in new development Rather, pixels should 
be written using the high-performance Irectw command. 

This routine is available only in immediate mode. 

When there are only 12 color bitplanes available, the lower 4 bits of ^ 
each color are ignored. 



c 
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NAME 

xfpt, xfpti, xfpts, xfpt2, xfpt2i, xfpt2s, xfpt4 ? xfpt4i, xfpt4s - multi- 
plies a point by the current matrix in feedback mode 

FORTRAN SPECIFICATION 

subroutine xfpt(x, y, z) 
real x, y, z 

subroutine xfpti(x, y, z) 
integer*4 x, y, z 

subroutine xfpts(x, y, z) 
integer*2 x, y, z 

subroutine xfpt2(x, y) 
real x, y 

subroutine xfpt2i(x, y) 
integer*4 x, y 

subroutine xfpt2s(x, y) 
integer*2 x, y 

subroutine xfpt4(x, y, z, w) 
real x, y, z, w 

subroutine xfpt4i(x, y, z, w) 
integer*4 x, y, z 9 w 

subroutine xfpt4s(x, y, z, w) 
integer*2 x, y, z, w 

PARAMETERS 

x expects the x coordinate of a point. 

y expects the y coordinate of a point. 

z expects the z coordinate of a point. Used only by the 3-D and 4-D 
versions of the routines; 0.0 is assumed by the others. 

w expects the w coordinate of a point Used only by the 4-D version of 
the routines; 1.0 is assumed by the others. 
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DESCRIPTION 

xfpt multiplies the specified point (x,y,0.0, 1.0), (x,y,z, 1.0), or 
(x,y, z, w) by the current matrix in the Geometry Pipeline. The 4-D 
result is not clipped or scaled, and is placed in the feedback buffer. 

SEE ALSO 

Graphics Library Programming Guide, Feedback Mode 

NOTES 

This routine is available only in feedback mode; otherwise it is ignored. 

This routine functions only on IRIS-4D B and G models, and we advise 
against its use for new development. 

The processor can access full words only on full-word boundaries, xfpt 
does not guarantee such alignment See the Graphics Library 
Programming Guide, Feedback Mode, for information on successful 
alignment. 



c 



( 
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NAME 

zbuffe - enable or disable z-buffer operation in the current framebuffer 

FORTRAN 77 SPECIFICATION 

subroutine zbuffe(bool) 
logical bool 

PARAMETERS 

tool expects one of two possible values: 
.TRUE, enables z-buffer operation. 
.FALSE, disables z-buffer operation. 

DESCRIPTION 

zbuffe turns z-buffer mode off or on for the current framebuffer, one of 
normal, popup, overlay, and underlay, as specified by drawmo. The z- 
buffer is a bitplane bank that is associated with a single framebuffer, and 
that stores a depth value for each pixel in that framebuffer. When z- 
buffer operation is enabled, the depth value associated with each incom- 
ing pixel is compared to the depth value stored in the framebuffer at that 
pixel location. The comparison function is specified by zfunct. If the 
comparison passes, the incoming pixel color is written into the color bit- 
plane bank or banks, and the incoming pixel depth is written into the z- 
buffer bitplanes. The current z write mask controls which z-buffer bit- 
planes are written with new depth data. 

If the comparison fails, no change is made to the contents of either the 
color bitplane banks or the z-buffer bitplane bank. In some cases, how- 
ever, a change is made to the contents of the stencil bitplanes. 

By default z-buffer operation is disabled in all framebuffers. 

SEE ALSO 

drawmo, getzbu, lsetde, stenci, zclear, zdraw, zfunct, zsourc, zwrite 
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NOTE 



On some models z-buffer hardware is optional. Call getgde(GDBNZB) 
to determine whether z-buffer hardware is available. 

Currently z-buffer operation is supported only in the normal frame- 
buffer. To insure compatibility with future releases of the GL, make | 
calls to zbuffe only while draw mode is NORMAL. ^ 



BUG 



IRIS-4D GT and GTX models accept z-buffer commands, and support 
z-buffer operation using the normal z-buffer, when the draw mode is 
PUPDRA, OVERDR, and UNDERD. This operation is incorrect and 
will be changed in a future release of the Graphics Library. 



( 



( 
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NAME 

zclear - initializes the z-buffer of the current framebuffer 

FORTRAN 77 SPECIFICATION 
subroutine zclear 

PARAMETERS 
none 

DESCRIPTION 

zclear sets the z-buffer in the area of the viewport to 
getgde(GDZMAX), the largest positive z value supported. Typically 
zclear is called prior to rendering each frame. If you intend to clear the 
color bitplanes as well as the z-buffer, or if you require control of the 
value written to the z-buffer, call czclea instead of zclear. 

Because only the normal framebuffer includes a z buffer, zclear should 
be called only while draw mode is NORMAL. Also, the current z wri- 
temask controls which z-buffer bitplanes are modified during zclear 
execution, and screenmask, when it is set to a subregion of the viewport, 
bounds the cleared region. Other drawing modes, including polygon fill 
pattern, stenciling, texture mapping, writemask, and z buffering, have no 
effect on the operation of zclear. 

After zclear executes, the graphics position is undefined. 

SEE ALSO 

drawmo, getgde, scrmas, setpat, stenci, texbin, wmpack, writem, zbuffe, 
zwrite 
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NAME 

zdraw - enables or disables drawing to the z-buffer 

FORTRAN 77 SPECIFICATION 

subroutine zdraw(b) 
logical b 

PARAMETERS 

h expects one of two possible values: 

.TRUE, enables drawing of colors into the z-buffer. 
•FALSE, disables drawing of colors into the z-buffer. 

DESCRIPTION 

When zbuffe is .TRUE., depth values are drawn into the z-buffer as a 
side effect of drawing to the front or back bitplane buffers. When 
zbuffe is .FALSE., however, it is possible to treat the z-buffer as a 
third color bitplane buffer, zdraw enables or disables drawing of color 
values into the z-buffer. 

By default, and after each call to gconfi, zdraw is .FALSE.. All com- 
binations of values for backbu, frontb, and zdraw are valid while the 
normal framebuffer is in double buffer mode. While the normal frame- 
buffer is in single buffer mode, backbu is ignored, and frontb can be 
disabled only while zdraw is enabled. 

Because only the normal framebuffer includes a z-buffer, zdraw is 
significant only while the normal framebuffer is enabled for drawing 
(see drawmo). zdraw should not be called while drawing to the over- 
lay, underlay, or pop-up framebuffers. 

SEE ALSO 

backbu, drawmo, frontb, gconfi, zbuffe 



c 
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NOTE 

On the Personal Iris, calling zdraw(.TRUE.) selects the z-buffer as the 
destination of the pixel writing routines: writep, writer, rectwr, 
Irectw, and rectco. Geometric drawing routines (lines, polygons, etc.) 
cannot draw into the z-buffer even when zdraw is enabled. These com- 
mands will continue to draw into the front and back buffers (as selected) 
when zdraw is on. 

On the Personal Iris, when zdraw is on it is not possible to write pixels 
into the frame buffer, regardless of the settings of frontb and backbu. 

On all machines, operation while both zdraw and zbuffe are .TRUE. 
is undefined. 



BUGS 



On the Personal Iris, when zdraw is enabled, geometric drawing com- 
mands (lines, polygons, etc.) will update depth values into the z-buffer. 

IRIS-4D VGX models do not support zdraw while the normal frame- 
buffer is configured with stencil bitplanes. (see stensi.) 
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NAME 

zfunct - specifies the function used for z-buffer comparison by the 
current framebuffer 

FORTRAN 77 SPECIFICATION 

subroutine zfunct(func) 
integer*4 func 

PARAMETERS 

func expects one of eight possible flags used when comparing z values. 
The available flags are: 

ZFNEVE, the z-buffer function never passes. 

ZFLESS, the z-buffer function passes if the incoming pixel z 
value is less than the z value stored in the z-buffer bitplanes. 

ZFEQUA, the z-buffer function passes if the incoming pixel z 
value is equal to the z value stored in the z-buffer bitplanes. 

ZFLEQU, the z-buffer function passes if the incoming pixel z 
value is less than or equal to the z value stored in the z-buffer bit- 
planes. (This is the default value.) 

ZFGREA, the z-buffer function passes if the incoming pixel z 
value is greater than the z value stored in the z-buffer bitplanes. 

ZFNOTE, the z-buffer function passes if the incoming pixel z 
value is not equal to the z value stored in the z-buffer bitplanes. 

ZFGEQU, the z-buffer function passes if the incoming pixel z 
value is greater than or equal to the z value stored in the z-buffer 
bitplanes. 

ZFALWA, the z-buffer function always passes. 

DESCRIPTION 

zfunct specifies the function used to compare each incoming pixel z 
value with the z value present in the z-buffer bitplanes. For example, if 
func is ZFLESS and the incoming pixel z value is less than the z value in 
the z-buffer bitplanes, the comparison passes. Refer to the zbuffe 
manual page for an explanation of z-buffer operation in the cases of z 



Version 3.0 -1- April 1990 



c 



c 



c 



zfunct Graphics Reference, FORTRAN zfunct 

function pass and failure. 

A separate zfunct mode is retained by each of the framebuffers: nor- 
mal, popup, overlay, and underlay. The current draw mode determines 
which z function value is used, and which is modified by zfunct. 

SEE ALSO 

drawmo, zbuffe, zsourc 

NOTES 

This subroutine is available only in immediate mode. 

Currently z-buffer operation is supported only in the normal frame- 
buffer. To insure compatibility with future releases of the GL, make 
calls to zfunct only while draw mode is NORMAL. 

On the Personal Iris, if you use zfunct with czclea you can increase the 
speed of buffer clearing. 
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NAME 

zsourc - selects the source for z-buffering comparisons 

FORTRAN 77 SPECIFICATION 

subroutine zsourc(src) 
integer*4 src 

PARAMETERS 

src expects one of two possible values: 

ZSRCDE, z-buffering is done by depth comparison (default). 
ZSRCCO, z-buffering is done by color comparison. 

DESCRIPTION 

By default z-buffer comparisons are done on depth data. However, in 
certain cases, it can be useful to z-buffer by comparing color values, 
especially the color index values generated by the linesmooth and 
pntsmooth hardware. When the src parameter is ZSRCDE, the z-buffer 
operation is normal. When the src parameter is ZSRCCO, however, 
source and destination color values are compared to determine which 
pixels the system draws. In this mode, the zbuffer is not updated when a 
pixel is written. 

A separate zsourc mode is retained by each of the framebuffers: nor- 
mal, popup, overlay, and underlay. The current draw mode determines 
which z source mode is used, and which is modified by zsourc. 

SEE ALSO 

drawmo, gversi, linesm, pntsmo, zbuffe, zfunct 

NOTES 

This subroutine is available only in immediate mode. 

This subroutine does not function on IRIS-4D B or G models. 



c 
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Currently z-buffer operation is supported only in the normal frame- 
buffer. To insure compatibility with future releases of the GL, make 
calls to zsourc only while draw mode is NORMAL. 



BUGS 



IRIS-4D GT and GTX models support zsourc(ZSRCCO) only for non- 
suhpixel positioned lines drawn after a linesm(SMLON) call. 

On early serial numbers of the Personal Iris, ZSRCDE is the only sup- 
ported setting for this routine. For compatibility, they accept the call 
zsourc(ZSCCCO), but it has the same effect as calling 
zfunct(ZFALWA), which turns off z value comparison. This allows the 
unrestricted drawing of color values into the front and back buffers and 
depth values into the z-buffer. Use gversi to deteimine which type of 
Personal Iris you have. 

IRIS-4D VGX models support zsourc(ZSRCCO) only in color map 
mode. Stencil operation is undefined in this case. 

This routine is of limited utility, and we do not recommend the use of it. 
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NAME 

zwrite - specifies a write mask for the z-buffer of the current frame- 
buffer 

FORTRAN 77 SPECIFICATION 

zwrite(mask) 
integer*4 mask; 

PARAMETERS 

mask expects a mask indicating which z-buffer bitplanes are read only 
and which can be written to. Z-buffer bitplanes that correspond 
to zeros in the mask are read only. Z-buffer bitplanes that 
correspond to ones in the mask can be written. 

DESCRIPTION 

zwrite specifies a mask used to control which z-buffer bitplanes are 
written, and which are read only. A separate mask is maintained by 
each of the framebuffers, normal, popup, overlay, and underlay. The 
mask affects both writes to the z-buffer that are the result of z-buffer 
pixel operation, and writes resulting from zclear operation. 

zwrite is ignored while drawing directly to the z-buffer, as when zdraw 
is TRUE. In this case the current writemask applies to the z-buffer as 
well as to the color bitplanes. 

SEE ALSO 

wmpack, writem, zbuffer, zdraw 

NOTES 

This subroutine is available only in immediate mode. 

Currently z-buffer operation is supported only in the normal frame- 
buffer. To insure compatibility with future releases of the GL, make 
calls to zwrite only while draw mode is NORMAL. | 



( 
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BUGS 

This subroutine does not function on IRIS-4D B or G models. 

IRIS-4D GT and GTX models, and the Personal Iris, currently support a 
subset of z write mask functionality. Specifically, zwrite either enables 
or disables the writing of all z-buffer bitplanes. The mask passed to 
zwrite will disable z-buffer writes if it is zero; otherwise all z-buffer bit- 
planes are written. To assure upward compatibility with the IRIS-4D 
VGX and other future models, call zwrite with mask equal to either or 
$FFFFFFFF when all-or-nothing update is desired. 
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Permuted Index 



on the screen into a line in 

- flushs the 
server - opens a 

- closes the 

- selects which 

- blocks until the 
passes a single token through the 

endsur - delimit a 

- controls the shape of a 

endtri - delimit a 

/the current value of a trimmed 

linear trimming curve for 

for the display of trimmed 

- controls the shape of a 
- blocks until the Geometry 

single token through the Geometry 

- gets the current 

- sets the range of 
- sets the current color in 

/c3s, c4f, c4i, c4s - sets the 
- gets a copy of the 
- returns the current 

- operate on the 
per color component in the 

- writes and displays 

- specify a plane against which 

graphics window in front of 

current graphics window behind 

for an image - 

structure for a new menu - 

of overlay colors - 

of underlay colors - 

- specify 

- specify 

- specify 

- specify 
arci, arcs - draw a circular 

arcf s - draw a filled circular 

arc arcfi, 

arci, 

- specifies the 

fog density for per-vertex 

valuators - 

screen - 

- pops the 

- pushes down the 

off - turns 

- returns whether 
process from being put into the 

- sets the color of the textport 



Key Word Man Page 

3-D world coordinates /a point mapw 

DGL client buffer gflush 

DGL connection to a graphics dglope 

DGL server connection dglclo 

GL framebufferis drawable drawmo 

Geometry Pipeline is empty finish 

Geometry Pipeline - passth 

NURBS surface definition bgnsur, 

NURBS surface nurbss 

NURBS surface trimming loop bgntri, 

NURBS surfaces display property getnur 

NURBS surfaces /a piecewise pwlcur 

NURBS surfaces - sets a property setnur 

NURBS trimming curve nurbsc 

Pipeline is empty finish 

Pipeline - passes a passth 

RGB color values gRGBco 

RGB colors used for depth-cueing lRGBra 

RGB mode RGBcol 

RGB (or RGBA) values for the/ c3f, 

RGB values for a color map entry getmco 

RGB writemask gRGBma 

accumulation buffer acbuf 

accumulation buffer /of bitplanes acsize 

all bitplanes single 

all geometry is clipped clippl 

all other windows /the current winpop 

all other windows - places the winpus 

allocates an area of the window viewpo 

allocates and initializes a newpup 

allocates bitplanes for display overla 

allocates bitplanes for display underl 

alpha test function afunct 

antialiasing of lines linesm 

antialiasing of points pntsmo 

antialiasing of polygons polysm 

arc arc, 

arc arcfi, arcf, 

arcfs - draw a filled circular arcf, 

arcs - draw a circular arc arc, 

aspect ratio of a graphics window keepas 

atmospheric effects - specify fogver 

attaches the cursor to two attach 

attaches the input focus to a scmat 

attribute stack * popatt 

attribute stack pushat 

backfacing polygon removal on and backfa 

backfacing polygons will appear getbac 

background /prevents a graphical foregr 

background pageco 
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- registers the screen 

- sets current 

- defines a 

- selects a 
bounding box and minimum/ bbox2i, 

- rings the keyboard 
of the beep of the keyboard 

current window - 
access to a subset of available 

- clears the color 
colors - allocates 
colors -allocates 

- returns the number of available 

the/ - specify the number of 

- writes and displays all 
planes - specify the number of 

- grants write permission to 

- controls screen 

- sets the screen 

- specifies a window without any 

/bbox2s - culls and prunes to 

back the current computed screen 

/- culls and prunes to bounding 

current computed screen bounding 

- control the screen 
the lights on the dial and button 

- sets the dial and button 
- operate on the accumulation 

component in the accumulation 
drawing to the back or front 

- flushs the DGL client 

- sets the display mode to double 

array of pixels into the frame 
- defines a minimum time between 

- indicates which 

- exchanges the front and back 

- sets the lights on the dial and 

- sets the dial and 
the state (up or down) of a 

- ties two valuators to a 
values for/ c3i, c3s, c4f, c4i, 

- returns the 

raster/ - returns the maximum 

cmov2s - updates the current 

- returns the current 
- returns the cursor 

- returns the character 
menu entry - sets the display 

- sets the cursor 

- draws a string of raster 

queue - 



background process imakeb 

basis matrices , patchb 

basis matrix defbas 

basis matrix used to draw curves curveb 

bbox2s - culls and prunes to bbox2, 

bell ringbe 

bell - sets the duration setbel 

binds window constraints to the wincon 

bitplanes - grants write RGBwri 

bitplanes and the z-buffer/ czclea 

bitplanes for display of overlay overla 

bitplanes for display of underlay underl 

bitplanes getpla 

bitplanes per color component in acsize 

bitplanes single 

bitplanes to be used as stencil stensize 

bitplanes writem 

blanking blanks 

blanking timeout , blankt 

borders nobord 

bounding box and minimum pixel/ bbox2, 

bounding box - read getscr 

box and minimum pixel radius bbox2, 

box - read back the getscr 

box , scrbox 

box - sets setdbl 

box text display dbtext 

buffer acbuf 

buffer /of bitplanes per color , acsize 

buffer /- enable and disable backbu, 

buffer gflush 

buffer mode double 

buffer /- draws a rectangular rectwr, 

buffer swaps swapin 

buffers are enabled for writing getbuf 

buffers of the normal framebuffer swapbu 

button box setdbl 

button box text display dbtext 

button - returns getbut 

button tie 

c4s - sets the RGB (or RGB A) c3f, 

character characteristics getdes 

character height in the current gethei 

character position /cmov2i, cmov, 

character position getcpo 

characteristics getcur 

characteristics getdes 

characteristics of a given pop up setpup 

characteristics setcur 

characters on the screen charst 

checks the contents of the event qtest 
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circfi, 

circi, circs - outlines a 

circfi, circfs - draws a filled 

circi, 

specified value - 

the z-buffer simultaneously - 

- flushs the DGL 
against which all geometry is 



window - 

cmovi, cmovs, cmov2, cmov2i, 

- selects either depth or 

simultaneously - clears the 

active - change the effect of 

the number of bitplanes per 

- returns the current 

- sets the current 
mode colorf - sets the 

depth-cueing - sets range of 

display mode that bypasses the 

maps - organizes the 

- organizes the 

rate - changes a 

a copy of the RGB values for a 

- changes a 

returns the number of the current 

mode. - sets 

- returns the current 
correction - defines a 

- cycles between 
mode - selects one of the small 

- sets the 

- sets the 
- computes a blended 

- gets the current RGB 

(or RGB A) values for the current 

integer - specifies RGB A 

the current draw mode 

object - 

- controls 
- allows the system to draw 

into a texture - 

screen into a line in 3-D world 

on the screen into 2-D world 

the viewer's position in polar 

positions as absolute screen 

automatic generation of texture 



circfs - draws a filled circle circf, 

circle circ, 

circle circf, 

circs - outlines a circle circ, 

clear the stencil planes to a sclear 

clears the color bitplanes and czclea 

clears the viewport clear 

client buffer gflush 

clipped - specify a plane clippl 

clkoff - control keyboard click clkon, 

closes a filled polygon pclos 

closes an object definition closeo 

closes the DGL server connection dglclo 

closes the identified graphics winclo 

cmov2s - updates the current/ cmov, 

color as the source for/ zsourc 

color bitplanes and the z-buffer czclea 

color commands while lighting is lmcolo 

color component in the/ - specify acsize 

color getcol 

color in RGB mode RGBcol 

color index in the current draw color, 

color indices used for lshade 

color map - sets a rendering and RGBmod 

color map as a number of smaller multim 

color map as one large map onemap 

color map entry at a selectable blink 

color map entry - gets getmco 

color map entry mapcol 

color map - getmap 

color map mode as the current cmode 

color map mode getcmm 

color map ramp for gamma gammar 

color maps at a specified rate cyclem 

color maps provided by multimap setmap 

color of text in the textport textco 

color of the textport background pageco 

color value for a pixel blendf 

color values gRGBco 

color vector /c4s - sets the RGB c3f, 

color with a single packed 32-bit cpack 

colorf - sets the color index in color, 

compacts the memory storage of an compac 

compatibility modes glcomp 

concave polygons concav 

convert a 2-dimensional image texdef 

coordinates /maps a point on the mapw 

coordinates - maps a point mapw2 

coordinates - defines polarv 

coordinates - interpret graphics screen 

coordinates - specify texgen 
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an optional zoom - 

the zoom for rectangular pixel 

- returns a 

color map entry - gets a 

current viewport - gets a 

a color map ramp for gamma 

entire screen gbegin - 



object relative to an existing/ - 



and minimum/ bbox2i, bbox2s - 

- gets the 

- returns the 

- sets 
/cmov2i, cmov2s - updates the 

- returns the 

- returns the 

- sets the 

- returns the number of the 

- returns the 
the RGB (or RGB A) values for the 

box - read back the 

- returns the 

- returns the type of the 

- sets the color index in the 

- returns the 
disable z-buffer operation in the 

- initializes the z-buffer of the 
mask for the z-buffer of the 

- gets the 
/move2, move2i, move2s - moves the 

all other windows -places the 

lower-left comer - moves the 

- assigns the icon title for the 

of all other windows - moves the 

viewport to the dimensions of the 

- returns the identifier of the 
the size and position of the 

- sets the 
- adds a title bar to the 

- returns the 

- returns the 

- sets a repeat factor for the 

- returns the 
/- multiplies a point by the 

- returns the 

-sets the 

- sets polor map mode as the 

- deletes a tag from the 



copies a rectangle of pixels with rectco 

copies and writes - specifies rectzo 

copy of a transformation matrix getmat 

copy of the RGB values for a getmco 

copy of the dimensions of the getvie 

correction - defines . gammar 

create a window that occupies the ............ ginit, 

creates a graphics subwindow swinop 

creates a graphics window winope 

creates a new tag within an newtag 

creates an event queue entry qenter 

creates an object makeob 

culls and prunes to bounding box bbox2, 

current RGB color values gRGBco 

current RGB writemask gRGBma 

current basis matrices patchb 

current character position * cmov, 

current character position getcpo 

current color getcol 

current color in RGB mode RGBcol 

current color map getmap 

current color map mode getcmm 

current color vector /c4s - sets c3f, 

current computed screen bounding getscr 

current display mode .. getdis 

current display monitor getmon 

current draw mode colorf color, 

current drawing mode getdra 

current framebuffer - enable or zbuffe 

current framebuffer zclear 

current framebuffer /a write zwrite 

current graphics position S et gP° 

current graphics position to a/ move, 

current graphics window behind winpus 

current graphics window by its winmov 

current graphics window iconti 

current graphics window in front winpop 

current graphics window /sets the ............ reshap 

current graphics window winget 

current graphics window /changes winpos 

current graphics window winset 

current graphics window wintit 

current hitcode gethit 

current linestyle getlst 

current linestyle lsrepe 

current linewidth getlwi 

current matrix in feedback mode xfpt, 

current matrix mode getmmo 

current matrix mode mmode 

current mode. cmode 

current open object deltag 
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whether a tag exists in the 

- returns the index of the 

maximum character height in the 

- returns the 

- returns the 

- returns the 

- returns the 
- has no function in the 

- premultiplies the 
surfaces display/ - returns the 

a copy of the dimensions of the 
returns the screen upon which the 
- binds window constraints to the 

- returns the 
for z-buffer comparison by the 

visibility by window 

- returns the 

- sets the 
- sets the origin of a 

- defines the type andor size of 

- defines a 

- attaches the 

cursof - control 

- draws a 
/a piecewise linear trimming 

the shape of a NURBS trimming 
- draws a rational 

- draws a 
of line segments used to draw a 

- draws a series of 

- draws a series of 



gamma correction 



buffer swaps - 
transformation - 
transformation - 

clipping mask - 
environment - 

light source, or lighting/ - 

cursor - 

polar coordinates - 

endsur - delimit a NURBS surface 

- closes an object 

- opens an object 



current open object - returns istag 

current pattern getpat 

current raster font /returns the gethei 

current raster font number getfon 

current screen mask getscr 

current shading model getsm 

current state of a valuator getval 

current system getlsb 

current transformation matrix multma 

current value of a trimmed NURBS getnur 

current viewport - gets getvie 

current window appears - getwsc 

current window wincon 

current writemask getwri 

current /the function used zfunct 

cursof - control cursor curson, 

cursor characteristics getcur 

cursor characteristics setcur 

cursor curori 

cursor cursty 

cursor glyph defcur 

cursor to two valuators attach 

cursor visibility by window curson, 

curve crv 

curve for NURBS surfaces pwlcur 

curve - controls nurbsc 

curve rcrv 

curve segment curvei 

curve segment - sets number curvep 

curve segments crvn 

curve segments rcrvn 

deallocates a menu freepu 

defines a basis matrix defbas 

defines a color map ramp for gammar 

defines a cursor glyph defcur 

defines a linestyle deflin 

defines a menu defpup 

defines a minimum time between swapin 

defines a perspective projection perspe 

defines a perspective projection window 

defines a raster font defras 

defines a rectangular screen scrmas 

defines a texture mapping tevdef 

defines a viewing transformation lookat 

defines or modifies a material, lmdef 

defines patterns defpat 

defines the type andor size of cursty 

defines the viewer's position in polarv 

definition bgnsur, 

definition closeo 

definition for editing editob 
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open object 



z-buffering/ - selects either 

- sets the 

- indicates whether 

- turns 

the range of RGB colors used for 

range of color indices used for 

- gets graphics system 

- returns the file 

- sets the viewport to the 

viewport - gets a copy of the 

- sets the 
front buffer f rontb - enable and 
current framebuffer - enable or 

given pop up menu/ - sets the 

sets the dial and button box text 

lampof - control the keyboard 

- numbers a routine in the 
ones - overwrites existing 

- returns the current 
color map - sets a rendering and 

mode - sets the 
- returns the type of the current 

- allocates bitplanes for 

- sets a property for the 

- allocates bitplanes for 
value of a trimmed NURBS surfaces 

- writes and 
menu - 

- sets the display mode to 

arci, arcs - 

number of line segments used to 

arcfi, arcfs - 

rectangle sboxfi, sboxfs - 

sboxi, sboxs - 

- allows the system to 

- selects a basis matrix used to 

the color index in the current 

rdr2, rdr2i, rdr2s - relative 

rpdr2i, rpdr2s - relative polygon 

drawi, draws, draw2, draw2i, 



circfi, circfs - 

polfs, polf2, polf2i, polf2s - 

draws, draw2, draw2i, draw2s - 

pnti, pnts, pnt2, pnt2i, pnt2s - 



deletes a tag from the current deltag 

deletes an object >. delobj 

deletes routines from an object objdel 

depth or color as the source for . zsourc 

depth range .. Isetde 

depth-cue mode is on or off getdcm 

depth-cue mode on and off depthc 

depth-cueing - sets IRGBra 

depth-cueing -sets lshade 

description . getgde 

descriptor of the event queue qgetfd 

dimensions of the current/ reshap 

dimensions of the current getvie 

dimensions of the picking region picksi 

disable drawing to the back or backbu, 

disable z-buffer operation in the zbuffe 

display characteristics of a setpup 

display - dbtext 

display lights lampon, 

display list maketa 

display list routines with new objrep 

display mode ........ getdis 

display mode that bypasses the RGBmod 

display mode to double buffer double 

display monitor getmon 

display of overlay colors overla 

display of trimmed NURBS surfaces ....... setnur 

display of underlay colors underl 

display property /the current getnur 

displays all bitplanes single 

displays the specified pop-up dopup 

double buffer mode double 

draw a circular arc arc, 

draw a curve segment - sets curvep 

draw a filled circular arc arcf, 

draw a filled screen -aligned sboxf, 

draw a screen-aligned rectangle sbox, 

draw concave polygons . concav 

draw curves curveb 

draw mode colorf - sets color, 

draw rdri, rdrs, rdr, 

draw rpdri, rpdrs, rpdr2, rpdr, 

draw2s - draws a line draw, 

draws a curve crv 

draws a curve segment curvei 

draws a filled circle circf, 

draws a filled polygon polfi, polf, 

draws a line drawi, draw, 

draws a point pnt, 

draws a rational curve rcrv 

draws a rational surface patch rpatch 
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pixels into the frame/ lrectw - 



/splfs, splf2, sph°2i, splf2s - 
characters on the screen - 



back or front buffer f rontb - 

operation in the current/ - 

a closed line 

mode 

aline 

interpretation of vertex/ 

a polygon 

a quadrilateral strip 

colored - controls whether the 

definition 

a triangle mesh 

trimming loop 

- creates an 

- administers 
the file descriptor of the 

- reads the first entry in the 

- empties the 

- checks the contents of the 
device from making entries in the 

buffers of the normal/ - 
- returns whether a tag 

- returns whether an object 

endfeedback - control 

a point by the current matrix in 

queue - returns the 

circfi, circfs - draws a 

arcfi, arcfs - draw a 

- closes a 

polf2, polf2i, polf2s - draws a 

splf2i, splf2s - draws a shaded 

sboxfi, sboxfs - draw a 

atmospheric effects - specify 

- defines a raster 

- selects a raster 
height in the current raster 

- returns the current raster 

- selects which GL 

and back buffers of the normal 

z-buffer operation in the current 

the z-buffer of the current 



draws a rectangular array of rectwr, 

draws a series of curve segments crvn 

draws a series of curve segments rcrvn 

draws a shaded filled polygon splf, 

draws a string of raster charst 

draws a surface patch patch 

draws an instance of an object callob 

empties the event queue qreset 

enable and disable drawing to the backbu, 

enable or disable z-buffer zbuffe 

endclo - delimit the vertices of bgnclo, 

endfeedback - control feedback feedba, 

endlin - delimit the vertices of bgnlin, 

endpoi - delimit the bgnpoi, 

endpol - delimit the vertices of bgnpoi, 

endpup - obsolete routines pupmod, 

endqst - delimit the vertices of bgnqst, 

ends full-screen mode endful 

ends of a line segment are lsback 

endsur - delimit a NURBS surface bgnsur, 

endtme - delimit the vertices of bgntme, 

endtri - delimit a NURBS surface bgntri, 

event queue entry qenter 

event queue qcontr 

event queue - returns qgetfd 

event queue qread 

event queue qreset 

event queue qtest 

event queue /the specified unqdev 

exchanges the front and back swapbu 

exists in the current open object istag 

exists isobj 

exits graphics gexit 

feedback mode feedba, 

feedback mode /- multiplies xfpt, 

file descriptor of the event qgetfd 

filled circle circf, 

filled circular arc arcf, 

filled polygon pclos 

filled polygon polfi, polfs, polf, 

filled polygon /splfs, sph°2, splf, 

filled screen-aligned rectangle sboxf, 

fog density for per-vertex fogver 

font defras 

font for drawing text strings font 

font /the maximum character gethei 

font number getfon 

framebufferis drawable drawmo 

framebuffer /exchanges the front swapbu 

framebuffer - enable or disable zbuffe 

framebuffer - initializes zclear 
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for the z-buffer of the current framebuffer /a write mask . zwrite 

- swap multiple framebuffers simultaneously mswapb 

drawing to the back or front/ frontb - enable and disable . backbu, 

graphics window - specifies fudge values that are added to a fudge 

- ends full-screen mode endful 

- defines a color map ramp for gamma correction gammar 

occupies the entire screen gbegin - create a window that ginit, 

specify a plane against which all geometry is clipped - clippl 

hardware registers getvid - set and get video setvid, 

- defines a cursor glyph defcur 

- exits graphics gexit 

version information - returns graphics hardware and library gversi 

a 2-D, 3-D, or 4-D vertex to the graphics pipe /v4s - transfers v2d, 

- gets the current graphics position getgpo 

point /move2s - moves the current graphics position to a specified move, 

screen coordinates - interpret graphics positions as absolute screen 

- opens a DGL connection to a graphics server dglope 

- resets graphics state greset 

- creates a graphics subwindow swinop 

- gets graphics system description getgde 

windows - places the current graphics window behind all other winpus 

comer - moves the current graphics window by its lower-left winmov 

discrete/ - specifies that a graphics window change size in stepun 

fudge values that are added to a graphics window - specifies fudge 

- returns the position of a graphics window getori 

- returns the size of a graphics window getsiz 

the icon title for the current graphics window. - assigns iconti 

other/ - moves the current graphics window in front of all winpop 

- specifies the aspect ratio of a graphics window keepas 

- specifies the maximum size of a graphics window maxsiz 

- specifies the minimum size of a graphics window minsiz 

preferred location and size of a graphics window - specifies the prefpo 

specifies the preferred size of a graphics window - prefsi 

to the dimensions of the current graphics window /the viewport reshap 

- closes the identified graphics window winclo 

the identifier of the current graphics window - returns winget 

- creates a graphics window winope 

size and position of the current graphics window - changes the winpos 

- sets the current graphics window winset 

- adds a title bar to the current graphics window wintit 

information - returns graphics hardware and library version gversi 

getvid - set and get video hardware registers setvid, 

- returns the maximum character height in the current raster font gethei 

- returns the current hitcode gethit 

- sets the hitcode to zero clearh 

- specifies the icon size of a window iconsi 

graphics window. - assigns the icon title for the current iconti 

integer for use as an object identifier - returns a unique genobj 

graphics window -returns the identifier of the current winget 

object - returns the identifier of the currently open getope 

- convert a 2-dimensional image into a texture texdef 
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an area of the window for an image - allocates viewpo 

colorf - sets the color index in the current draw mode color, 

- returns the index of the current pattern getpat 

menu - allocates and initializes a structure for a new newpup 

- initializes the name stack initna 

- initializes the textport textin 

current framebuffer - initializes the z-buffer of the zclear 

sequence on an optional video/ - initiates a command transfer videoc 

a specified location - inserts routines in an object at objins 

- rings the keyboard bell ringbe 

the duration of the beep of the keyboard bell - sets setbel 

clkoff - control keyboard click clkon, 

lampof - control the keyboard display lights lampon, 

display lights lampof - control the keyboard lampon, 

- selects a new material, light source, or lighting model lmbind 

- defines or modifies a material, light source, or lighting model lmdef 

effect of color commands while lighting is active - change the lmcolo 

a new material, light source, or lighting model - selects lmbind 

a material, light source, or lighting model /or modifies lmdef 

- control the keyboard display lights lampof lampon, 

- sets the lights on the dial and button box setdbl 

delimit the vertices of a closed line endclo - bgnclo, 

- delimit the vertices of a line endlin ... bgnlin, 

draw2, draw2i, draw2s - draws a line drawi, draws, draw, 

maps a point on the screen into a line in 3-D world coordinates - mapw 

- controls whether the ends of a line segment are colored lsback 

curve segment - sets number of line segments used to draw a curvep 

surfaces - describes a piecewise linear trimming curve for NURBS pwlcur 

- defines a linestyle „ deflin 

- returns the current linestyle getlst 

a repeat factor for the current linestyle - sets lsrepe 

- selects a linestyle pattern setlin 

- returns the linestyle repeat count getlsr 

- returns the state of linestyle reset mode getres 

- returns the current linewidth getlwi 

numbers a routine in the display list - . maketa 

- reads a list of valuators at one time getdev 

- overwrites existing display list routines with new ones objrep 

- loads a name onto the name stack loadna 

- loads a transformation matrix loadma 

delimit a NURBS surface trimming loop endtri - bgntri, 

array of pixels into CPU memory lrectr - reads a rectangular rectre, 

array of pixels into the frame/ lrectw - draws a rectangular rectwr, 

mode that bypasses the color map /sets a rendering and display RGBmod 

- organizes the color map as a number of smaller maps multim 

- organizes the color map as one large map „ onemap 

- changes a color map entry at a selectable rate blink 

of the RGB values for a color map entry - gets a copy getmco 

- changes a color map entry mapcol 

the number of the current color map - returns getmap 

- sets color map mode as the current mode cmode 
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- returns the current color map mode getcmm 

the color map as one large map - organizes . onemap 

- defines a color map ramp for gamma correction gammar 

- defines a texture mapping environment tevdef 

current/ - specifies a write mask for the z-buffer of the zwrite 

- returns the current screen mask getscr 

a rectangular screen clipping mask - defines scrmas 

- sets current basis matrices patchb 

- defines a basis matrix defbas 

a copy of a transformation matrix - returns getmat 

multiplies a point by the current matrix in feedback mode /xfpt4s - xfpt, 

- loads a transformation matrix , loadma 

- returns the current matrix mode . getmmo 

- sets the current matrix mode .. mmode 

the current transformation matrix - premultiplies multma 

- pops the transformation matrix stack popmat 

- pushes down the transformation matrix stack pushma 

- selects a basis matrix used to draw curves curveb 

specifies minimum object size in memory - chunks 

array of pixels into CPU memory /- reads a rectangular rectre, 

- compacts the memory storage of an object compac 

adds items to an existing pop-up menu - addtop 

- defines a menu defpup 

- displays the specified pop-up menu , dopup 

characteristics of a given pop up menu entry - sets the display setpup 

- deallocates a menu freepu 

initializes a structure for a new menu - allocates and newpup 

the vertices of a triangle mesh endtme - delimit bgntme, 

- toggles the triangle mesh register pointer swaptm 

- scales and mirrors objects scale 

- sets the current color in RGB mode RGBcol 

- sets color map mode as the current mode cmode 

color index in the current draw mode colorf - sets the , color, 

the display mode to double buffer mode - sets double 

- ends full-screen mode endful 

- turns off picking mode endpic 

- turns off selecting mode endsel 

endfeedback - control feedback mode feedba, 

- returns the current color map mode getcmm 

- returns the current display mode getdis 

- returns the current drawing mode getdra 

- returns the current matrix mode , getmmo 

the state of linestyle reset mode -returns getres 

- puts the system in selecting mode gselec 

- indicates whether depth-cue mode is on or off getdcm 

- sets the current matrix mode mmode 

- turns depth-cue mode on and off depthc 

- specify pixel transfer mode parameters pixmod 

- puts the system in picking mode ... pick 

color maps provided by multimap mode - selects one of the small setmap 

- sets a rendering and display mode that bypasses the color map RGBmod 



Version 3.0 - 1 - April 1 990 



( 



( 



Permuted Index 



Graphics Reference, FORTRAN 



Permuted Index 



- sets the display 

by the current matrix in feedback 

the type of the current display 

- sets the 

rmv2, rmv2i, rmv2s - relative 

rpmv2i, rpmv2s - relative polygon 

movei, moves, move2, move2i, 

/moves, move2, move2i, move2s - 

by its lower-left comer - 

in front of all other windows - 

the small color maps provided by 

- pops a 

- pushes a new 

- loads a 

- initializes the 
- loads a name onto the 

- pops a name off the 

- pushes a new name on the 
the front and back buffers of the 

- specifies a 

- specify renormalization of 

- inserts routines in an 

- draws an instance of an 

compacts the memory storage of an 

- closes an 

- opens an 

- deletes an 
a tag from the current open 

- returns whether an 
identifier of the currently open 

a unique integer for use as an 
a tag exists in the current open 

- creates an 
- deletes routines from an 

- creates a new tag within an 

- specifies minimum 



mode to double buffer mode double 

mode /xfpt4s - multiplies a point xfpt, 

monitor - returns getmon 

monitor type setmon 

move rmvi, rmvs, rmv, 

move rpmvi, rpmvs, rpmv2, rpmv, 

move2s - moves the current/ move, 

moves the current graphics/ move, 

moves the current graphics window winmov 

moves the current graphics window winpop 

multimap mode - selects one of setmap 

name off the name stack popnam 

name on the name stack pushna 

name onto the name stack loadna 

name stack initna 

name stack loadna 

name stack popnam 

name stack pushna 

normal framebuffer - exchanges swapbu 

normal n3f 

normals nmode 

object at a specified location objins 

object callob 

object - compac 

object definition closeo 

object definition for editing editob 

object delobj 

object - deletes deltag 

object exists isobj 

object - returns the getope 

object identifier - returns genobj 

object - returns whether istag 

object makeob 

object objdel 

object relative to an existing/ newtag 

object size in memory chunks 

obsolete routine RGBcur 

obsolete routine RGBran 

obsolete routine gRGBcu 

obsolete routine getdep 

obsolete routine getoth 

obsolete routine getpor 

obsolete routine getsha 

obsolete routine ismex 

obsolete routine normal 

obsolete routine setdep 

obsolete routine setsha 

obsolete routine shader 

obsolete routine smooth 

obsolete routine spclos 

obsolete routine winatt 
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endpup - obsolete routines , pupmod, 

backfacing polygon removal on and off - turns backfa 

- turns depth-cue mode on and off depthc 

polygon removal on and off - turns frontfacing frontf 

whether depth-cue mode is on or off - indicates getdcm 

whether z-buffering is on or off - returns getzbu 

- turns off picking mode endpic 

- turns off selecting mode endsel 

- pops a name off the name stack popnam 

/a command transfer sequence on an optional video peripheral videoc 

turns backfacing polygon removal on and off - backfa 

- turns depth-cue mode on and off depthc 

turns frontfacing polygon removal on and off - frontf 

whether depth-cue mode is on or off - indicates getdcm 

- returns whether z-buffering is on or off getzbu 

- operate on the accumulation buffer acbuf 

- sets the lights on the dial and button box setdbl 

- pushes a new name on the name stack pushna 

a string of raster characters on the screen - draws charst 

coordinates - maps a point on the screen into 2-D world mapw2 

world coordinates - maps a point on the screen into a line in 3-D mapw 

- paints a row of pixels on the screen . writeR 

- paints a row of pixels on the screen writep 

graphics server - opens a DGL connection to a dglope 

editing - opens an object definition for editob 

number of smaller maps - organizes the color map as a multim 

large map - organizes the color map as one onemap 

projection transformation ortho2 - define an orthographic ortho, 

ortho2 - define an orthographic projection/ ortho, 

cirri, circs - outlines a circle circ, 

polys, poly2, poly2i, poly2s - outlines a polygon polyi, poly, 

recti, rects - outlines a rectangular region rect, 

bitplanes for display of overlay colors - allocates overla 

routines with new ones - overwrites existing display list objrep 

screen - paints a row of pixels on the writeR 

screen - paints a row of pixels on the writep 

- alter the operating parameters of the stencil stencil 

- specify pixel transfer mode parameters pixmod 

- draws a surface patch patch 

of curves used to represent a patch - sets the number patchc 

at which curves are drawn in a patch - sets the precision patchp 

- draws a rational surface patch rpatch 

rectangles - selects a pattern for filling polygons and setpat 

returns the index of the current pattern - getpat 

- selects a linestyle pattern setlin 

- defines patterns defpat 

of a/ pdri, pdrs, pdr2, pdr2i, pdr2s - specifies the next point pdr, 

sequence on an optional video peripheral /a command transfer videoc 

transformation - defines a perspective projection perspe 

transformation - defines a perspective projection window 

for NURBS surfaces - describes a piecewise linear trimming curve pwlcur 
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a blended color value for a 

/the zoom for rectangular 

to bounding box and minimum 

- specify 

specifies a logical operation for 

polygon vertices - controls the 

is clipped - specify a 

bitplanes to be used as stencil 

- clear the stencil 

of a/ pmvi, pmvs, pmv2, pmv2i, 

pnti, pnts, pnt2, pnt2i, 

/xfpt4i, xfpt4s - multiplies a 

graphics position to a specified 

pdr2i, pdr2s - specifies the next 

pmv2s - specifies the first 

world coordinates - maps a 

in 3-D world/ - maps a 

pnt2, pnt2i, pnt2s - draws a 

of vertex routines as 

- specify antialiasing of 

defines the viewer's position in 

polfi, polfs, polf2, polf2i, 

polyi, polys, poly 2, poly2i, 

- delimit the vertices of a 

rpdr2, rpdr2i, rpdr2s - relative 

rpmv2, rpmv2i, rpmv2s - relative 

- closes a filled 

- specifies the next point of a 

- specifies the first point of a 
polf2i, polf2s - draws a filled 

poly2i, poly2s - outlines a 

- turns backfacing 

- turns frontfacing 
splf2s - draws a shaded filled 

the placement of point, line, and 



stack - 

- adds items to an existing 

- displays the specified 
- updates the current character 
- returns the current character 

- gets the current graphics 

- defines the viewer's 

- returns the 

window - changes the size and 

/- moves the current graphics 

coordinates - interpret graphics 
rot - rotate graphical 



pixel - computes blendf 

pixel copies and writes rectzo 

pixel radius /- culls and prunes bbox2, 

pixel transfer mode parameters pixmod 

pixel writes - logico 

placement of point, line, and subpix 

plane against which all geometry clippl 

planes - specify the number of stensize 

planes to a specified value sclear 

pmv2s - specifies the first point pmv, 

pnt2s -draws a point pnt, 

point by the current matrix in/ xfpt, 

point /move2s - moves the current move, 

point of a polygon /pdrs, pdr2, pdr, 

point of a polygon /pmv2, pmv2i, pmv, 

point on the screen into 2-D mapw2 

point on the screen into a line mapw 

point pnti, pnts, pnt, 

points /the interpretation bgnpoi, 

points pntsmo 

polar coordinates - polarv 

polf2s - draws a filled polygon polf, 

poly2s - outlines a polygon P°tyi 

polygon endpol bgnpoi, 

polygon draw rpdri, rpdrs, rpdr, 

polygon move rpmvi, rpmvs, rpmv, 

polygon pclos 

polygon /pdrs, pdr2, pdr2i, pdr2s pdr, 

polygon /pmvs, pmv2, pmv2i, pmv2s pmv, 

polygon polfi, polfs, polf2, polf, 

polygon polyi, polys, poly 2, poly, 

polygon removal on and off backfa 

polygon removal on and off frontf 

polygon /splfs, splf2, splf2i, splf, 

polygon vertices - controls subpix 

pops a name off the name stack popnam 

pops the attribute stack popatt 

pops the transformation matrix popmat 

pops the viewport stack popvie 

pop-up menu addtop 

pop-up menu dopup 

position /cmov2, cmov2i, cmov2s cmov, 

position getcpo 

position getgpo 

position in polar coordinates polarv 

position of a graphics window getori 

position of the current graphics winpos 

position to a specified point move, 

positions and sizes the textport textpo 

positions as absolute screen screen 

primitives rotate, 
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- translates graphical primitives transl 

- prevents a graphical process from being put into the/ foregr 

- registers the screen background process .. imakeb 

ortho2 - define an orthographic projection transformation ortho, 

- defines a perspective projection transformation perspe 

- defines a perspective projection transformation window 

trimmed NURBS surfaces - sets a property for the display of .............. setnur 

a trimmed NURBS surfaces display property /the current value of getnur 

bbox2i, bbox2s - culls and prunes to bounding box and/ bbox2, 

stack - pushes a new name on the name pushna 

- pushes down the attribute stack . pushat 

matrix stack - pushes down the transformation pushma 

- pushes down the viewport stack pushvi 

- reads multiple entries from the queue blkqre 

- creates an event queue entry qenter 

- administers event queue qcontr 

the file descriptor of the event queue - returns qgetfd 

the first entry in the event queue - reads qread 

- empties the event queue , qreset 

checks the contents of the event queue - qtest 

from making entries in the event queue /the specified device unqdev 

specified device is enabled for queuing - returns whether the isqueu 

to bounding box and minimum pixel radius /bbox2s - culls and prunes bbox2, 

- sets the depth range lsetde 

depth-cueing - sets the range of RGB colors used for lRGBra 

depth-cueing - sets range of color indices used for Ishade 

- assigns an initial value and a range to a valuator setval 

- draws a string of raster characters on the screen charst 

- defines a raster font defras 

strings - selects a raster font for drawing text font 

character height in the current raster font /returns the maximum gethei 

- returns the current raster font number getfon 

a color map entry at a selectable rate -changes .....* blink 

between color maps at a specified rate -cycles ...... cyclem 

- specifies the aspect ratio of a graphics window keepas 

- draws a rational curve rcrv 

- draws a rational surface patch rpatch 

rdri, rdrs, rdr2, rdr2i, rdr2s - relative draw rdr, 

screen bounding box - read back the current computed getscr 

for pixels that various routines read - sets the source readso 

optional zoom - copies a rectangle of pixels with an rectco 

sboxs - draw a screen-aligned rectangle sboxi, sbox, 

- draw a filled screen -aligned rectangle sboxfi, sboxfs sboxf, 

rectfi, rectf s - fills a rectangular area rectf, 

CPU memory Irectr - reads a rectangular array of pixels into rectre, 

the frame/ lrectw - draws a, rectangular array of pixels into rectwr, 

writes - specifies the zoom for rectangular pixel copies and rectzo 

recti, rects - outlines a rectangular region rect, 

- defines a rectangular screen clipping mask scrmas 

rectfi, rectfs - fills a rectangular area rectf, 

region recti, rects - outlines a rectangular rect, 
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- toggles the triangle mesh 

- set and get video hardware 

process - 

rdri, rdrs, rdr2, rdr2i, rdr2s - 

rmvi, rmvs, rmv2, rmv2i, rmv2s - 

rpdrs, rpdr2, rpdr2i, rpdr2s - 

rpmvs, rpmv2, rpmv2i, rpmv2s - 

/a new tag within an object 

bypasses the color map - sets a 

- control the 

- returns the state of linestyle 

- waits for a vertical 
rmvi, rmvs, rmv2, rmv2i, 

rot- 

rpdri, rpdrs, rpdr2, rpdr2i, 

rpmvi, rpmvs, rpmv2, rpmv2i, 

screen-aligned rectangle sboxfi, 

rectangle sboxi, 

- registers the 

- controls 
- sets the 

- read back the current computed 

- control the 
of raster characters on the 

- defines a rectangular 

graphics positions as absolute 

a program write to the entire 

a window that occupies the entire 

- maps a point on the 

- maps a point on the 

- returns the current 

- attaches the input focus to a 
that a program does not need 

placed - selects the 
window appears - returns the 

- paints a row of pixels on the 

- paints a row of pixels on the 

- draws a series of curve 

- draws a series of curve 
segment - sets number of line 

- turns off 

- puts the system in 

draw curves - 

source, or lighting model - 

polygons and rectangles - 

text strings - 



register pointer swaptm 

registers getvid setvid, 

registers the screen background imakeb 

relative draw rdr, 

relative move rmv, 

relative polygon draw rpdri, rpdr, 

relative polygon move rpmvi, rpmv, 

relative to an existing tag newtag 

rendering and display mode that RGBmod 

rendering of polygons polymo 

reset mode getres 

resets graphics state greset 

retrace period gsync 

rmv2s - relative move rmv, 

rot - rotate graphical primitives rotate, 

rotate graphical primitives rotate, 

rpdr2s - relative polygon draw rpdr, 

rpmv2s - relative polygon move rpmv, 

sboxfs - draw a filled sboxf, 

sboxs - draw a screen-aligned sbox, 

screen background process imakeb 

screen blanking blanks 

screen blanking timeout blankt 

screen bounding box getscr 

screen box scrbox 

screen - draws a string charst 

screen clipping mask somas 

screen coordinates - interpret screen 

screen -allows fullsc 

screen gbegin - create ginit, 

screen into 2-D world coordinates mapw2 

screen into a line in 3-D world/ mapw 

screen mask getscr 

screen scmat 

screen space - specifies noport 

screen upon which new windows are scmse 

screen upon which the current getwsc 

screen writeR 

screen writep 

segments crvn 

segments rcrvn 

segments used to draw a curve curvep 

selecting mode endsel 

selecting mode gselec 

selects a basis matrix used to curveb 

selects a linestyle pattern setlin 

selects a new material, light lmbind 

selects a pattern for filling setpat 

selects a raster font for drawing font 

selects a texture environment tevbin 

selects a texture function texbin 
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the source for z-buff ering/ - 

maps provided by multimap mode - 

windows are placed - 

drawable - 

- closes the DGL 

a DGL connection to a graphics 

of trimmed NURBS surfaces - 

that bypasses the color map - 

current linestyle - 

current mode. - 

to draw a curve segment - 

for depth-cueing - 

the/ c3i, c3s, c4f, c4i, c4s - 

current draw mode colorf - 

textport - 

background - 

mode - 



display - 

picking region - 

of a given pop up menu entry - 

buffer mode - 

the keyboard bell - 

button box - 

represent a patch - 

curves are drawn in a patch - 
for depth-cueing - 

various routines read - 

dimensions of the current/ - 

- returns the current 

- selects the 

- specifies RGB A color with a 

- specifies RGBA writemask with a 

Pipeline - passes a 

routines read - sets the 

either depth or color as the 

splfi, splfs, splf2, splf2i, 

- initializes the name 

- loads a name onto the name 

- pops the attribute 

- pops the transformation matrix 

- pops a name off the name 



selects either depth or color as zsourc 

selects one of the small color setmap 

selects the screen upon which new scmse 

selects the shading model shadem 

selects which GL framebufferis drawmo 

server connection dglclo 

server - opens dglope 

sets a property for the display setnur 

sets a rendering and display mode RGBmod 

sets a repeat factor for the Isrepe 

sets color map mode as the cmode 

sets current basis matrices patchb 

sets number of line segments used curvep 

sets range of color indices used lshade 

sets the RGB (or RGBA) values for c3f , 

sets the color index in the color, 

sets the color of text in the textco 

sets the color of the textport pageco 

sets the current color in RGB RGBcol 

sets the current graphics window winset 

sets the current matrix mode mmode 

sets the cursor characteristics setcur 

sets the depth range Isetde 

sets the dial and button box text dbtext 

sets the dimensions of the picksi 

sets the display characteristics setpup 

sets the display mode to double double 

sets the duration of the beep of setbel 

sets the hitcode to zero clearh 

sets the lights on the dial and setdbl 

sets the monitor type setmon 

sets the number of curves used to patchc 

sets the origin of a cursor curori 

sets the precision at which patchp 

sets the range of RGB colors used IRGBra 

sets the screen blanking timeout blankt 

sets the source for pixels that readso 

sets the viewport to the reshap 

shading model getsm 

shading model shadem 

single packed 32-bit integer cpack 

single packed integer wmpack 

single token through the Geometry passth 

source for pixels that various readso 

source for z-buffering/ - selects zsourc 

splf2s - draws a shaded filled/ splf , 

stack initna 

stack .loadna 

stack popatt 

stack popmat 

stack popnam 
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- pops the viewport 

- pushes down the attribute 
down the transformation matrix 

- pushes a new name on the name 

- pushes down the viewport 
deep a window is in the window 

- resets graphics 

- returns the current 

- returns the 

- returns the 
- specify which 

number of bitplanes to be used as 

value -clear the 

the operating parameters of the 

- compacts the memory 

the screen - draws a 

the width of the specified text 

a raster font for drawing text 

- allocates and initializes a 

screen-space limit - 

- creates a graphics 

endsur - delimit a NURBS 

- controls the shape of a NURBS 

- draws a 

- draws a rational 
endtri - delimit a NURBS 

simultaneously - 

- gets graphics 

- reconfigures the 
- has no function in the current 

- puts the 

- puts the 
- allows the 

object - returns whether a 

- deletes a 
a unique integer for use as a 

an object relative to an existing 

an existing tag - creates a new 

- sets the dial and button box 

- sets the color of 
the width of the specified 

selects a raster font for drawing 
- sets the color of the 

- sets the color of text in the 

- initializes the 

- positions and sizes the 

- control the visibility of the 

- specify a 

- specify automatic generation of 

- selects a 

- selects a 



stack popvie 

stack pushat 

stack - pushes pushma 

stack . pushna 

stack pushvi 

stack - measures how windep 

state greset 

state of a valuator getval 

state of linestyle reset mode getres 

state (up or down) of a button getbut 

stencil bits can be written swrite 

stencil planes - specify the stensize 

stencil planes to a specified sclear 

stencil - alter stencil 

storage of an object compac 

string of raster characters on charst 

string - returns strwid 

strings - selects font 

structure for a new menu newpup 

subdivide lines and polygons to a scrsub 

subwindow swinop 

surface definition bgnsur, 

surface nurbss 

surface patch patch 

surface patch rpatch 

surface trimming loop bgntri, 

swap multiple framebuffers mswapb 

system description getgde 

system gconfi 

system getlsb 

system in picking mode pick 

system in selecting mode gselec 

system to draw concave polygons concav 

tag exists in the current open istag 

tag from the current open object deltag 

tag - returns gentag 

tag - creates a new tag within newtag 

tag within an object relative to newtag 

text display dbtext 

text in the textport textco 

text string - returns strwid 

text strings - font 

textport background pageco 

textport textco 

textport textin 

textport textpo 

textport tpoff tpon, 

texture coordinate t 

texture coordinates texgen 

texture environment tevbin 

texture function texbin 
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- defines a 
a 2-dimensional image into a 

- defines a minimum 
reads a list of valuators at one 

- sets the screen blanking 
Pipeline - passes a single 

the textport 

- defines a viewing 

- returns a copy of a 

- loads a 

- premultiplies the current 

- pops the 
- pushes down the 

define an orthographic projection 
defines a perspective projection 
defines a perspective projection 

- delimit the vertices of a 

- toggles the 

- describes a piecewise linear 

- controls the shape of a NURBS 

endtri - delimit a NURBS surface 

on and off - 

on and off - 



bitplanes for display of 
/v3f, v3i, v3s, v4d, v4f, v4i, 

- returns the current state of a 

- filters 

an initial value and a range to a 

- reads a list of 

- attaches the cursor to two 

- ties two 

values for the current color 

graphics hardware and library 

- delimit the interpretation of 

- transfers a 2-D, 3-D, or 4-D 

- waits for a 
endclo - delimit the 
endlin - delimit the 
endpol - delimit the 
endqst - delimit the 
endtme - delimit the 
of point, line, and polygon 

- defines a 
- clears the 

of the dimensions of the current 

- pops the 
- pushes down the 

current graphics/ - sets the 



texture mapping environment tevdef 

texture - convert texdef 

time between buffer swaps swapin 

time - ... getdev 

timeout blankt 

token through the Geometry passth 

tpoff - control the visibility of tpon, 

transformation . lookat 

transformation matrix getmat 

transformation matrix loadma 

transformation matrix multma 

transformation matrix stack popmat 

transformation matrix stack pushma 

transformation ortho2 - ortho, 

transformation - perspe 

transformation - window 

triangle mesh endtme bgntme, 

triangle mesh register pointer swaptm 

trimming curve for NURBS surfaces pwlcur 

trimming curve nurbsc 

trimming loop bgntri, 

turns backfacing polygon removal backfa 

turns depth-cue mode on and off depthc 

turns frontfacing polygon removal frontf 

turns off picking mode endpic 

turns off selecting mode endsel 

underlay colors - allocates underl 

v4s - transfers a 2-D, 3-D, or/ v2d, 

valuator getval 

valuator motion noise 

valuator - assigns setval 

valuators at one time getdev 

valuators attach 

valuators to a button tie 

vector /- sets the RGB (or RGBA) c3f, 

version information - returns gversi 

vertex routines as points endpoi bgnpoi, 

vertex to the graphics pipe /v4s v2d, 

vertical retrace period , gsync 

vertices of a closed line bgnclo, 

vertices of a line bgnlin, 

vertices of a polygon bgnpoi, 

vertices of a quadrilateral strip bgnqst, 

vertices of a triangle mesh bgntme, 

vertices /controls the placement subpix 

viewing transformation lookat 

viewport .clear 

viewport - gets a copy getvie 

viewport stack popvie 

viewport stack pushvi 

viewport to the dimensions of the reshap 
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the screen upon which the current 

- places the current graphics 

- moves the current graphics 

- specifies that a graphics 

window -binds 

- control cursor visibility by 

- allocates an area of the 

that are added to a graphics 

the position of a graphics 

- returns the size of a graphics 

- specifies the icon size of a 
- moves the current graphics 

- measures how deep a 

the aspect ratio of a graphics 

the maximum size of a graphics 

the minimum size of a graphics 

location and size of a graphics 

the preferred size of a graphics 

of the current graphics 

how deep a window is in the 

screen gbegin - create a 

- closes the identified graphics 
window constraints to the current 

of the current graphics 

- creates a graphics 
position of the current graphics 

- sets the current graphics 
title bar to the current graphics 

- specifies a 

on the screen into a line in 3-D 

a point on the screen into 2-D 

available bitplanes - grants 

the current/ - specifies a 

- grants 

- allows a program 

- returns the current RGB 

- returns the current 
integer - specifies RGBA 

a logical operation for pixel 

for rectangular pixel copies and 

which buffers are enabled for 

/xfpt2i, xfpt2s, xfpt4, xfpt4i, 

- specifies the function used for 

framebuffer - initializes the 

- specifies a write mask for the 
framebuffer - enable or disable 

the color bitplanes and the 

or disables drawing to the 

depth or color as the source for 

- returns whether 



window appears - returns getwsc 

window behind all other windows winpus 

window by its lower-left comer winmov 

window change size in discrete/ stepun 

window constraints to the current wincon 

window cursof curson, 

window for an image viewpo 

window - specifies fudge values fudge 

window - returns getori 

window getsiz 

window iconsi 

window in front of all other/ winpop 

window is in the window stack windep 

window - specifies keepas 

window - specifies maxsiz 

window - specifies minsiz 

window - specifies the preferred prefpo 

window - specifies prefsi 

window /to the dimensions reshap 

window stack - measures windep 

window that occupies the entire ginit, 

window . winclo 

window - binds wincon 

window - returns the identifier winget 

window winope 

window - changes the size and winpos 

window winset 

window - adds a wintit 

window without any borders nobord 

world coordinates - maps a point mapw 

world coordinates - maps mapw2 

write access to a subset of RGBwri 

write mask for the z-buffer of zwrite 

write permission to bitplanes writem 

write to the entire screen fullsc 

writemask gRGBma 

writemask * getwri 

writemask with a single packed wmpack 

writes and displays all bitplanes single 

writes - specifies logico 

writes - specifies the zoom rectzo 

writing - indicates getbuf 

xfpt4s - multiplies a point by/ xfpt, 

z-buffer comparison by the/ zfunct 

z-buffer of the current zclear 

z-buffer of the current/ zwrite 

z-buffer operation in the current zbuffe 

z-buffer simultaneously - clears czclea 

z-buffer - enables zdraw 

z-buffering comparisons /either zsourc 

z-buffering is on or off getzbu 
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and writes - specifies the zoom for rectangular pixel copies rectzo 

of pixels with an optional zoom - copies a rectangle rectco 
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